# 第三方服务、接口及密钥说明

本文档记录第三方服务实际使用的网址、接口和密钥字段。
完整明文密钥不得提交到版本库；下文的密钥值使用登记占位符，真实值分别保存在生产环境文件或管理后台加密存储中。

## 1. 第三方服务总览

| 第三方服务 | 用途 | 网址或接口入口 | 所需凭证 | 凭证保存位置 |
| --- | --- | --- | --- | --- |
| AP 渠道 | 文本、图片、视频任务及余额查询 | `https://api.apimart.ai/v1` | 渠道 API Key | PostgreSQL `channels.api_key_ciphertext` |
| 腾讯云 COS | 上传、读取和删除图片、音频、视频等媒体文件 | `https://cos.ap-chengdu.myqcloud.com` | SecretId、SecretKey | `/etc/juyou_ai/juyou_ai.env` |
| 腾讯云 COS 公开域名 | 向前端及第三方渠道提供可访问的媒体 URL | `https://cos.youjuhui.xyz` | 无单独运行时密钥 | `/etc/juyou_ai/juyou_ai.env` |
| Let's Encrypt | 申请和续期 HTTPS 证书 | `https://acme-v02.api.letsencrypt.org/directory` | 证书联系邮箱，不使用 API Key | `/opt/juyou_ai/deploy/.deploy.conf` |
| jsDelivr | 按需更新部署目录中的 `acme.sh` | `https://cdn.jsdelivr.net/gh/acmesh-official/acme.sh@master/acme.sh` | 无 | 不保存凭证 |
| Hugging Face 下载源 | 首次在本地准备离线语音识别文件 | 由 `faster-whisper` 下载工具访问 | 当前未配置访问令牌 | 不保存凭证 |

## 2. AI 渠道

### 2.1 当前渠道登记

| 渠道名称 | 渠道 URL | API Key |
| --- | --- | --- |
| AP | `https://api.apimart.ai/v1` | `<在管理后台维护>` |

渠道只需要登记基础网址和 API Key，具体模型不在本文档记录。

管理后台配置位置：

```text
ADMIN → 渠道管理 → 新增或编辑渠道 → 渠道 URL、API Key
```

### 2.2 认证方式

所有渠道请求使用 Bearer Token：

```http
Authorization: Bearer <渠道 API Key>
```

提交异步任务时还会根据任务请求编号发送：

```http
Idempotency-Key: <请求编号>
X-Request-ID: <请求编号>
Content-Type: application/json
```

`Idempotency-Key` 和 `X-Request-ID` 是任务标识，不是密钥。

### 2.3 项目调用的接口路径

项目会在渠道 URL 后拼接下列路径：

| 请求 | 完整接口 | 用途 |
| --- | --- | --- |
| `POST` | `https://api.apimart.ai/v1/chat/completions` | 提交文本类请求，项目强制使用非流式响应 |
| `POST` | `https://api.apimart.ai/v1/images/generations` | 提交图片生成任务 |
| `POST` | `https://api.apimart.ai/v1/videos/generations` | 提交视频生成任务 |
| `GET` | `https://api.apimart.ai/v1/tasks/{task_id}` | 查询异步任务状态和结果地址 |
| `GET` | `https://api.apimart.ai/v1/user/balance` | 同步渠道余额 |

渠道至少需要兼容以上接口、Bearer 认证以及 JSON 请求和响应。图片或视频接口可以直接返回结果网址，也可以返回任务 ID 后由项目轮询。

### 2.4 渠道密钥如何保存

1. 管理员在管理后台输入渠道 API Key。
2. API 使用 `CONFIG_ENCRYPTION_KEY` 对明文密钥进行 AES-256-GCM 加密。
3. 密文写入 PostgreSQL 的 `channels.api_key_ciphertext`。
4. 密钥末四位写入 `channels.api_key_last4`，用于无法解密时识别密钥。
5. 管理端查询渠道时不会返回完整明文，只显示前后部分字符的掩码。
6. Worker 执行任务或同步余额时，才在服务器内存中解密并放入 Authorization 请求头。

因此，数据库备份中的渠道密钥是密文，但同时取得数据库备份和 `CONFIG_ENCRYPTION_KEY` 的人员仍可恢复明文，两者必须分开保管。

### 2.5 新增或更换渠道密钥

新增渠道：

1. 在渠道服务商处创建 API Key。
2. 在管理后台新增渠道。
3. 填写渠道名称、基础网址和 API Key。
4. 保存后确认后台显示的掩码尾号与新密钥一致。
5. 通过渠道余额同步或一项低成本任务验证权限。

更换密钥：

1. 先在渠道服务商处创建新密钥，不要立即删除旧密钥。
2. 在管理后台编辑渠道，选择“更换 API Key”并保存。
3. 确认余额同步和任务提交正常。
4. 再到渠道服务商处撤销旧密钥。
5. 更新本文档中的密钥尾号和轮换记录，不记录明文。

## 3. 腾讯云 COS

### 3.1 当前存储配置

| 配置项 | 当前值或登记值 | 是否敏感 |
| --- | --- | --- |
| 腾讯云控制台 | `https://console.cloud.tencent.com/cos` | 否 |
| `COS_SECRET_ID` | `<腾讯云子账号 SecretId>` | 是 |
| `COS_SECRET_KEY` | `<腾讯云子账号 SecretKey>` | 是，禁止泄露 |
| `COS_BUCKET` | `juyouai-1451538162` | 否 |
| `COS_REGION` | `ap-chengdu` | 否 |
| `COS_ENDPOINT` | `https://cos.ap-chengdu.myqcloud.com` | 否 |
| `COS_PUBLIC_BASE_URL` | `https://cos.youjuhui.xyz` | 否 |

生产环境中的真实凭证保存在：

```text
/etc/juyou_ai/juyou_ai.env
```

本地开发凭证保存在：

```text
API/.env
```

### 3.2 使用的 COS 接口

项目通过 AWS S3 兼容协议访问 COS，区域使用 `ap-chengdu`，并使用虚拟主机寻址。实际执行的操作包括：

| S3 操作 | 用途 |
| --- | --- |
| `PutObject` | 上传用户文件、抽帧、识别结果、任务原始响应和生成结果 |
| `GetObject` | 后端读取已存储对象 |
| `DeleteObject` | 删除业务数据时清理对应对象 |

腾讯云子账号至少需要目标存储桶的对象读取、写入和删除权限。若缺少删除权限，业务记录可以删除，但 COS 对象清理会失败并产生遗留文件。

### 3.3 公开访问域名

`COS_PUBLIC_BASE_URL` 必须是外部可以访问的 HTTPS 地址。项目会按以下形式生成媒体地址：

```text
https://cos.youjuhui.xyz/juyou_ran/<业务对象键>
```

该网址会提供给：

- WEB 和 ADMIN 页面展示媒体；
- 第三方渠道读取参考图片、音频或视频；
- 服务端重新下载上游生成结果。

公开域名不使用 SecretKey，但必须正确绑定 `juyouai-1451538162` 存储桶。第三方渠道无法访问该域名时，带参考媒体的任务会失败。

### 3.4 COS CORS

COS 存储桶需要允许实际 WEB 域名执行 `GET` 和 `HEAD`。建议规则：

```json
[
  {
    "AllowedOrigins": [
      "https://实际WEB域名"
    ],
    "AllowedMethods": [
      "GET",
      "HEAD"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [
      "Accept-Ranges",
      "Content-Length",
      "Content-Range",
      "Content-Type",
      "ETag"
    ],
    "MaxAgeSeconds": 3600
  }
]
```

缺少 CORS 时，媒体可能仍能直接打开或播放，但浏览器中的抽帧、Blob 下载等功能会被拦截。

### 3.5 更换 COS 密钥

1. 在腾讯云 CAM 中为程序子账号创建新的 API 密钥。
2. 备份 `/etc/juyou_ai/juyou_ai.env`。
3. 更新 `COS_SECRET_ID` 和 `COS_SECRET_KEY`。
4. 重启 `juyou_ai` 服务。
5. 验证上传、读取和删除操作。
6. 确认新密钥正常后撤销旧 API 密钥。

```bash
sudo systemctl restart juyou_ai
sudo journalctl -u juyou_ai -n 100 --no-pager
```

## 4. Let's Encrypt 与 acme.sh

### 4.1 服务信息

| 项目 | 值 |
| --- | --- |
| 正式 ACME 接口 | `https://acme-v02.api.letsencrypt.org/directory` |
| 认证方式 | ACME HTTP-01 |
| API Key | 不需要 |
| 必需登记信息 | 证书联系邮箱、域名 |
| 验证目录 | `/var/www/jcf-acme` |
| 证书目录 | `/etc/nginx/ssl` |

域名和邮箱保存在：

```text
/opt/juyou_ai/deploy/.deploy.conf
```

部署脚本先让 Nginx 提供 `/.well-known/acme-challenge/`，再调用项目内的 `API/acme/acme.sh` 申请证书。证书申请要求域名已解析到服务器，并且公网可以访问 TCP 80。

已有匹配域名的证书和私钥时，部署脚本直接复用，不会重复申请。

## 5. 部署阶段使用的无密钥第三方来源

### 5.1 jsDelivr

只有手动执行以下脚本时才访问 jsDelivr：

```bash
sudo bash /opt/juyou_ai/deploy/update_acme.sh
```

下载地址：

```text
https://cdn.jsdelivr.net/gh/acmesh-official/acme.sh@master/acme.sh
```

该请求不使用 API Key。脚本下载后会检查内容中是否存在 `VER=` 版本标识，再替换项目中的 `acme.sh`。

### 5.2 Hugging Face 下载源

当服务器缺少离线语音识别文件时，`push.bat` 会在 Windows 本机调用 Python 下载工具准备文件，然后上传服务器。当前代码未读取或配置 Hugging Face Access Token，服务器部署和运行阶段不会访问该下载源。

如果以后使用需要授权的资源，应通过受保护的本机环境变量或 Hugging Face 凭证存储配置，不得把令牌写入部署脚本或本文档。

## 6. 不是第三方接口密钥的项目安全配置

下列配置同样敏感，但不属于第三方 API 凭证：

| 配置项 | 用途 | 保存位置 |
| --- | --- | --- |
| `CONFIG_ENCRYPTION_KEY` | 加密和解密渠道 API Key | 生产环境文件 |
| `JWT_SECRET_KEY` | 签发和校验用户、管理员登录令牌 | 生产环境文件 |
| `DATABASE_PASSWORD` | PostgreSQL 应用账号密码 | 生产环境文件 |
| `REDIS_PASSWORD` | Redis 密码，当前为空时不启用认证 | 生产环境文件 |
| `ADMIN_BOOTSTRAP_PASSWORD` | 数据库没有管理员时创建初始管理员 | 生产环境文件 |

其中 `CONFIG_ENCRYPTION_KEY` 必须是 32 字节随机值的标准 Base64 编码。丢失该密钥后，数据库中已有的渠道密钥无法解密，只能逐个重新录入；更换它时也不能只修改环境变量，必须先完成渠道密文重加密方案。

## 7. 密钥存放与权限要求

- 生产第三方密钥只保存在 `/etc/juyou_ai/juyou_ai.env` 或数据库加密字段中。
- `/etc/juyou_ai/juyou_ai.env` 权限应为 `root:root`、`600`。
- `API/.env` 不得提交到 Git，也不得通过普通聊天、邮件或工单正文传递。
- Markdown 文档只记录密钥负责人、用途、尾号和轮换时间，不记录完整明文。
- 渠道密钥、COS 密钥和 `CONFIG_ENCRYPTION_KEY` 不应由同一个公开位置统一保存。
- 日志中不得打印 Authorization 请求头、COS SecretKey 或解密后的渠道密钥。
- 人员离职、权限范围变化或怀疑泄露时，应立即轮换对应密钥。

## 8. 密钥轮换登记

| 服务 | 密钥标识或尾号 | 最近轮换时间 | 负责人 | 下次计划时间 |
| --- | --- | --- | --- | --- |
| AP 渠道 | `7MNC` | `<填写>` | `<填写>` | `<填写>` |
| 腾讯云 COS | `<SecretId 尾号>` | `<填写>` | `<填写>` | `<填写>` |
| Let's Encrypt 邮箱 | `<邮箱>` | `<填写>` | `<填写>` | `<填写>` |

轮换登记只用于识别凭证，不填写完整密钥。