SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场chanjing-auth

chanjing-auth

安全与审计

查看项目

更新于 10-15 13:51

技能介绍

用途

Chanjing OAuth Authentication 是 Chanjing 平台所有功能的集中式认证管理技能，覆盖数字人、TTS、背景音乐、音效等功能的统一登录与凭据管理。它适用于以下场景：检查用户是否已通过 Chanjing 平台认证、引导用户完成 OAuth 登录流程、排查凭据或令牌问题，以及为 CI/CD 或无头环境设置认证。

注意：该技能不用于实际调用 Chanjing 服务 API，实际调用应委托给特定功能技能，例如 chanjing-digital-human。

主要能力

  • 检查当前认证状态（支持普通输出、退出码检查、JSON 输出）
  • 处理 OAuth CLI Web 登录流程
  • 管理访问令牌与刷新令牌的存储
  • 客户端自动刷新过期令牌并在 401 时自动重试
  • 支持 CI/CD 或无头环境通过刷新令牌认证
  • 提供 Studio 集成的认证状态端点与登录入口
  • 提供认证故障排查指引

使用方式

快速开始

# 检查当前认证状态
npx framevideo auth status

# 以退出码方式检查是否已认证
npx framevideo auth status --check

# 以 JSON 获取状态
npx framevideo auth status --json

如果未认证，使用下方的认证方法之一。

核心概念

OAuth CLI Web 登录标准流程：

  1. 用户运行 framevideo auth login 或在 Studio 中点击登录
  2. CLI 打开浏览器进入 Chanjing 授权页面
  3. 用户在浏览器中批准
  4. 浏览器重定向到本地回调服务器
  5. CLI 接收令牌并保存到凭据存储
  6. 所有 Chanjing 功能即可访问平台

凭据存储：令牌存储在 ~/.chanjing/credentials（遵循 CHANJING_CONFIG_DIR 环境变量），位于 oauth 块中：

{
  "oauth": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_at": 1234567890
  }
}

切勿读取、打印、记录或提交这些令牌。应使用 packages/cli/src/auth/store.ts 中的共享认证存储 API。

插件 API 客户端：所有 Chanjing API 请求使用 Authorization: Bearer <access_token> 请求头。客户端负责令牌过期刷新、401 自动重试和错误上报，位于 packages/cli/src/tts/chanjingOpenapi.ts。

认证方法

方法一：交互式登录（推荐），适用于开发与本地使用：

npx framevideo auth login

将打开浏览器进行 OAuth 流程，需要用户交互。

方法二：Studio 登录（对智能体友好），当与智能体协作且缺少 OAuth 时：

  1. 启动或复用预览服务器：npx framevideo preview
  2. 在浏览器中打开 Studio 项目 URL
  3. 导航到 Digital Human、Voice 或账户面板
  4. 点击登录按钮开始 OAuth 流程
  5. 完成浏览器授权
  6. 使用 npx framevideo auth status 验证

相较于仅使用 CLI 指引的优势：为用户提供可视化反馈、集成到自然工作流中、智能体可轮询状态端点。

方法三：CI/CD 或无头环境，适用于无浏览器的自动化环境：

  1. 从交互式登录会话获取刷新令牌
  2. 设置 CHANJING_REFRESH_TOKEN 环境变量
  3. CLI 将使用刷新令牌获取访问令牌

安全提示：将刷新令牌视为机密，使用安全密钥管理（GitHub Secrets、CI vault 等）。

缺少凭据时的用户体验

当智能体编写的工作流需要 Chanjing 功能但缺少认证时：

若预览可用（优先）：启动或复用 npx framevideo preview；在应用内浏览器中打开 Studio 项目 URL；导航到需要 Chanjing 的面板（Digital Human、Voice、账户）；点击登录以启动 OAuth CLI Web 登录；用户完成浏览器授权；重新检查认证状态，然后继续工作流。

若预览不可用：回退到仅 CLI 指引：npx framevideo auth login，然后继续工作流。

不应做的事：

  • ❌ 预览可用时仍停留在环境变量指引
  • ❌ 在凭据存储之外打印或保存令牌
  • ❌ 要求用户手动编辑 ~/.chanjing/credentials
  • ❌ 使用已弃用的 app_id、secret_key 或 CHANJING_OPENAPI_ACCESS_TOKEN

Studio 集成

Studio 通过插件路由提供认证状态和登录 UI。

认证状态端点：

GET /api/projects/:id/chanjing/auth/status

返回：

{
  "authenticated": true,
  "user": {
    "id": "...",
    "name": "..."
  }
}

用于引导用户到 Studio 登录后轮询认证状态。

登录按钮可用的位置：Digital Human 面板（Studio → Digital Human → Login）、Voice 面板（Studio → Voice → Login）、账户设置（Studio → Settings → Chanjing Account）。点击任意登录按钮都会触发相同的 OAuth CLI Web 登录流程。

故障排查

"Not authenticated" 错误：检查 npx framevideo auth status；修复方式 npx framevideo auth login。

令牌过期：客户端会自动刷新令牌。若刷新失败：

# 清除凭据并重新登录
rm ~/.chanjing/credentials
npx framevideo auth login

"Invalid token" 或 401 错误：凭据存储可能已损坏：

# 检查（脱敏输出）
npx framevideo auth status --json

# 清除并重新登录
rm ~/.chanjing/credentials
npx framevideo auth login

CI/CD 认证失败：验证 CHANJING_REFRESH_TOKEN 是否已设置；检查令牌是否过期（刷新令牌通常有效 30-90 天）；从交互式会话获取新的刷新令牌。

与其他技能的集成

chanjing-digital-human 使用此认证进行：列出数字人和声音、提交网站项目合成、轮询任务状态、下载生成的视频。

chanjing-media（计划中）使用此认证进行：背景音乐列表与下载、音效列表与下载。

framevideo-media 不使用此认证。本地 Kokoro TTS 离线且无需凭据。

安全最佳实践

  • 切勿打印令牌——不在日志、错误消息或智能体回复中
  • 使用凭据存储 API——不要直接读取 ~/.chanjing/credentials
  • 不要在 Git 中存放令牌——将凭据文件加入 .gitignore
  • 保护 CI 机密——对 CHANJING_REFRESH_TOKEN 使用密钥管理
  • 不要复制独立脚本——复用共享认证客户端，不要重复实现

验证

认证后：

# 应显示 "authenticated: true"
npx framevideo auth status

# 应列出可用资源
npx framevideo chanjing music categories --json

如果两者都成功，认证即正常工作。

参考

  • 认证存储实现：packages/cli/src/auth/store.ts
  • 插件 API 客户端：packages/cli/src/tts/chanjingOpenapi.ts
  • Studio 认证路由：见 chanjing-digital-human 技能的 references/studio-routes.md