---
title: 认证配置
navTitle: 认证配置
---
# 认证配置

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

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

## 认证方式{#methods}

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

CLI 默认使用 OAuth2：

```bash
succapp auth login <server-url>
```

使用 PAT 时显式加 `--pat`：

```bash
succapp auth login --pat <server-url>
```

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

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

## 本机认证文件{#files}

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

```text
~/.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}

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

```json
{
  "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}

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

PAT 示例：

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

OAuth2 示例：

```json
{
  "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` | 当前认证材料最近更新时间。 |

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

## 自动化场景配置{#automation}

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

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

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

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

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

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

```bash
succapp auth logout <server-url>
```

## 使用建议{#recommendations}

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