认证配置

SuccApp 工具访问服务器时需要认证。当前支持 OAuth2 和 PAT 两种方式：日常人工使用推荐 OAuth2；脚本、CI、远程终端和 AI 自动化流程更适合使用 PAT。

认证状态按服务器地址保存在本机，不写入 SuccApp 工作区的 .succapp/config.json，也不应提交到 Git 仓库。

认证方式

方式	适合场景	说明
OAuth2	日常开发、VS Code 图形化使用、有人值守的终端登录。	默认方式，需要打开浏览器完成人工授权。授权后工具会保存 access token 和 refresh token，并在 access token 过期时自动刷新。
PAT	脚本、CI、远程终端、AI Agent 自动化流程。	使用服务器签发的 Personal Access Token，不需要打开浏览器。建议按用途创建独立 PAT，并设置合适的有效期和权限范围。

CLI 默认使用 OAuth2：

succapp auth login <server-url>

使用 PAT 时显式加 --pat：

succapp auth login --pat <server-url>

自动化流程中，不要把 PAT 直接写进脚本文件。可以从受控密钥环境读取后通过标准输入传入：

printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat <server-url>

本机认证文件

默认情况下，SuccApp 工具把认证状态放在当前系统用户的 ~/.succapp/ 目录中：

~/.succapp/
├── auth.json
├── session.json
└── auth-state.lock

文件	用途
auth.json	保存稳定认证配置，例如服务器使用 OAuth2 还是 PAT、最近登录用户和更新时间。
session.json	保存当前认证材料，例如 PAT、OAuth2 access token、refresh token 和过期时间。
auth-state.lock	工具读写认证状态时使用的本机锁文件。

auth.json 和 session.json 都以规范化后的 server URL 作为 key。服务器地址、测试环境和生产环境不同，或同一服务器使用不同域名访问时，会保存为不同条目。

auth.json 格式

auth.json 不保存 token 原文，只保存稳定配置和登录摘要：

{
  "version": 1,
  "servers": {
    "https://succapp.example.com": {
      "authType": "oauth",
      "username": "admin",
      "userId": "admin",
      "lastLoginAt": "2026-06-05T10:00:00.000Z",
      "updatedAt": "2026-06-05T10:00:00.000Z"
    }
  }
}

字段说明：

字段	说明
version	文件格式版本，当前为 1。
servers	按 server URL 分组的认证配置。
authType	认证方式，只支持 oauth 或 pat。
username、userId	最近一次登录成功的用户摘要。
lastLoginAt、updatedAt	最近登录和更新认证状态的时间，使用 ISO 8601 字符串。

session.json 格式

session.json 保存真正用于请求服务器的认证材料。PAT 和 OAuth2 access token 都写在 token.value 中，因此这个文件属于敏感文件。

PAT 示例：

{
  "version": 1,
  "servers": {
    "https://succapp.example.com": {
      "authType": "pat",
      "token": {
        "type": "Bearer",
        "value": "personal-access-token"
      },
      "updatedAt": "2026-06-05T10:00:00.000Z"
    }
  }
}

OAuth2 示例：

{
  "version": 1,
  "servers": {
    "https://succapp.example.com": {
      "authType": "oauth",
      "token": {
        "type": "Bearer",
        "value": "access-token",
        "expiresAt": "2026-06-05T18:00:00.000Z",
        "scope": ["dev-tool"]
      },
      "refreshToken": "refresh-token",
      "updatedAt": "2026-06-05T10:00:00.000Z"
    }
  }
}

字段说明：

字段	说明
authType	当前服务器的认证方式，只支持 oauth 或 pat。
token.type	当前为 Bearer。
token.value	PAT 或 OAuth2 access token 原文。
token.expiresAt	access token 过期时间；PAT 不一定有该字段。
token.scope	token 的授权范围；由服务器返回。
refreshToken	OAuth2 refresh token，仅 OAuth2 登录时存在。
updatedAt	当前认证材料最近更新时间。

注意

session.json 包含可访问服务器的敏感 token。不要复制到工单、聊天记录、文档、日志或 Git 仓库中。

自动化场景配置

自动化流程建议使用 PAT，并把认证文件放到任务专用目录中，避免和人工开发环境共用 token。

可以通过环境变量指定认证文件位置：

export SUCCAPP_AUTH_SETTINGS_DIR=/path/to/succapp-auth
printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat <server-url>

也可以只指定 auth.json 文件路径，session.json 和锁文件会放在同一目录：

export SUCCAPP_AUTH_SETTINGS_FILE=/path/to/succapp-auth/auth.json
printf "%s" "$SUCCAPP_PAT" | succapp auth login --pat <server-url>

自动化任务结束后，如果不再复用这份认证状态，可以删除该目录，或执行：

succapp auth logout <server-url>

使用建议

1. 日常人工使用优先 OAuth2，减少 PAT 长期散落在本机和脚本中的风险。
2. 自动化流程使用 PAT，并为不同任务、环境和账号创建独立 PAT。
3. 测试环境和生产环境分开登录，不要混用服务器地址和 token。
4. 不要手工编辑 session.json；需要刷新认证状态时重新执行登录命令。
5. 如果每次打开都需要重新认证，先检查 PAT 是否过期或被撤销，OAuth2 refresh token 是否失效，以及当前系统用户是否能读取原来的认证目录。