# Token 与凭据轮换

个人 Token、给 MCP 和 API 用的服务账号，以及不停机地轮换它们。

最后校对于 2026-10-10

这页办完你会得到：一套能说清「哪个 Token 给谁用、上次什么时候用过、什么时候换」的做法， 以及一条换 Token 时不会把线上打断的操作顺序。

创建和使用 Token 的最短路径在 [个人 Token 认证](https://n9e.github.io/zh/docs/ai/token-auth.md)，这页讲的是之后的事。

## Token 是什么，不是什么[​](#token-是什么不是什么 "Token 是什么，不是什么的直接链接")

Token 是一个 UUID，挂在**某个用户**名下，代表「以这个用户的身份行动」。

* **它没有独立权限。** 拿 root 的 Token 就是 root，拿只读账号的 Token 就是只读账号。 想收窄一个集成能碰的东西，唯一的办法是换一个权限更小的账号来签发。
* **它不会过期。** 表里没有有效期字段，删掉才失效。
* **同一个 Token 三个入口通用**：`/api/n9e/*`、`/mcp`、`/a2a` 共用同一条认证链， 请求头默认是 `X-User-Token`。

所以「Token 管理」的实质是**账号管理**：一个用途一个账号、一个账号一个 Token， 出事的时候才有得查、有得停。

## 1. 给自动化建专用账号[​](#1-给自动化建专用账号 "1. 给��自动化建专用账号的直接链接")

不要把个人账号的 Token 交给 CI 或者 AI 客户端。按用途各建一个：

| 用途              | 建议角色                                           | 团队与业务组                       |
| ----------------- | -------------------------------------------------- | ---------------------------------- |
| AI 客户端只读接入 | `Guest`，或摘掉写权限的自定义角色                  | 加进一个对目标业务组**只读**的团队 |
| CI 里同步告警规则 | 自定义角色，只勾 `/alert-rules` 四件套             | 对应业务组**读写**                 |
| 外部系统读事件    | `Guest` + `/alert-cur-events`、`/alert-his-events` | 相关业务组只读                     |

建账号见[用户与团队](https://n9e.github.io/zh/docs/security/users-teams.md)，自定义角色见[角色与权限矩阵](https://n9e.github.io/zh/docs/security/roles.md)。

**别给这些账号 `Admin`**：`Admin` 会跳过业务组这一层，等于给了全量数据。

## 2. 不停机地轮换一个 Token[​](#2-不停机地轮换一个-token "2. 不停机地轮换一个 Token的直接链接")

Token 管理页在**头像菜单 → 个人中心 → Token 管理**（`/account/profile/token`）， 而且**只能管自己的 Token**——所以轮换服务账号的 Token 要先用那个账号登录。

顺序是「先建新的，再删旧的」，产品本身也强制这个顺序：删到只剩一个时再删会被拒绝 （`cannot delete the last token`）。

1. 用服务账号登录，进 Token 管理，点 **创建 Token**；
2. **Token 名称**必填，同一个用户下不能重名——所以名字里带上日期， 比如 `ci-2026-09`，下一轮就是 `ci-2026-12`；
3. 新行的 Token 值默认打码，点**查看**展开再复制；
4. 把新值换进客户端 / CI / 密钥管理器，跑一次真实调用；
5. 回到这一页，看旧 Token 那行的**最近使用时间**是否已经不再前进；
6. 确认之后删掉旧行，立刻生效。

预期结果：列表里只剩新那一行，业务侧没有一次 401。

第 5 步是这套流程的价值所在：`最近使用时间` 会告诉你还有没有谁在用旧凭据， 不用靠猜。它是每次认证成功时更新的，`-` 表示从来没用过。

## 3. 盘点在用的 Token[​](#3-盘点在用的-token "3. 盘点在用的 Token的直接链接")

界面上没有「全站 Token 列表」，`GET /api/n9e/self/token` 也只返回自己的。 所以盘点靠的是「一个用途一个账号」这条纪律：账号列表就是 Token 清单。

* 用户列表右上的**最后活跃时间**筛一遍，长期不活跃的服务账号大概率已经废弃；
* 每个服务账号下的 Token 数量应当是 1，多出来的通常是上一轮轮换没删干净；
* **删用户会连同他名下的全部 Token 一起删掉**——这就是离职处理的正确动作， 不需要先登录进去一个个删。

## 4. 别忘了另外几套凭据[​](#4-别忘了另外几套凭据 "4. 别忘了另外几套凭据的直接链接")

Token 只是其中一种。真正做一次凭据轮换，下面这些要一起过：

| 凭据                | 在哪儿换                         | 备注                                                                                                 |
| ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `root` 的密码       | 用户管理里的重置密码             | 默认口令 `root.2020` 是公开信息，装完就得改                                                          |
| 采集器 Basic Auth   | `[HTTP.APIForAgent.BasicAuth]`   | 改完要同步所有采集器，见[网络与 TLS 加固](https://n9e.github.io/zh/docs/security/network-tls.md)     |
| 服务间 Basic Auth   | `[HTTP.APIForService.BasicAuth]` | 配置文件里自带的那组示例账号密码是公开的，别沿用                                                     |
| 数据源账号密码      | 数据源编辑页                     | 非管理员看不到这些值，改完记得验证一次查询                                                           |
| SSO 的 ClientSecret | 系统配置 → 单点登录              | 建议放进加密变量，见[密钥管理](https://n9e.github.io/zh/docs/security/secrets.md)                    |
| 通知媒介的 Token    | 通知媒介配置                     | 同上                                                                                                 |
| 仪表盘匿名分享链接  | 仪表盘列表的公开设置             | 它是独立的令牌，改密码不会让它失效，见[匿名限时分享](https://n9e.github.io/zh/docs/query/sharing.md) |

配置文件里的那几项都支持密文存储，见[密钥管理](https://n9e.github.io/zh/docs/security/secrets.md)。

## 下一步[​](#下一步 "下一步的直接链接")

* 怎么建 Token、怎么发请求：[个人 Token 认证](https://n9e.github.io/zh/docs/ai/token-auth.md)
* 把凭据挪出配置文件：[密钥管理](https://n9e.github.io/zh/docs/security/secrets.md)
* 上线前整体过一遍：[安全检查清单](https://n9e.github.io/zh/docs/security/checklist.md)