ENTERPRISE OPERATIONS

日常管理与维护

维护企业 sub2api 的员工撤权、Key 轮换、单机冷备份、隔离恢复演练及升级流程,保留用量与配置记录。

本页由企业管理员和服务器维护人员操作,适用于本教程的 /opt/company-ai Docker Compose 部署。生产操作应安排维护窗口,并保留可恢复备份。

员工入职、调岗与离职

入职时,按员工与预算教程创建普通用户、分配预算并授权分组,将员工快速开始交给本人。

调岗时,先核对新岗位需要的模型和预算,再调整授权。撤销某个分组后,检查已有 Key 的实际可用范围;单纯修改员工姓名或备注不会改变权限。

离职或需要立即撤权时:

  1. 在用户管理中点击对应员工行的“禁用”,阻止该账号名下 Key 的新请求。
  2. 通过该行的“更多 → API密钥”核对全部 Key 的归属与状态。v0.2.21 的这个窗口没有停用 Key 按钮;需要让 Key 本身显示 inactive 时,可在交接阶段由员工先在个人“API 密钥”页面停用,再由管理员禁用账号。紧急撤权直接禁用用户即可,不必等待员工配合。
  3. 核对是否有该员工维护的共享项目 Key,安排接管和轮换。
  4. 使用已停用 Key 检查新请求被拒绝,确认其他员工继续可用。
  5. 保留员工历史记录用于对账,按企业制度决定后续删除与保留期限。
用户管理中 Alice 为禁用状态,Bob 和管理员仍为启用状态

图 S15-A:本地演示已禁用 Alice,Bob 保持启用。已额外验证:用户禁用后,即使名下 Key 仍显示 active,新的 Messages 请求也会返回 USER_INACTIVE。查看清晰原图。

管理员查看 Alice 的 API 密钥,Alice-Magpie 显示 inactive,完整 Key 未展示

图 S15-B:通过“更多 → API密钥”查看该员工的 Key。本例在禁用用户前已先停用个人 Key,因此显示 inactive;管理员在此窗口核对结果。查看清晰原图。

撤权不会撤回已经进入上游执行的请求,仍可能有在途请求完成并入账。若存在共享凭证,停用一个个人账号也不会自动轮换该共享凭证。

轮换员工 Key 和上游 Key

员工 Key 泄露时,停用对应 Key,创建新 Key,并更新该员工的工具配置。先判断泄露范围,再决定是否需要扩大轮换范围。

轮换 RootFlowAI 上游 Key 时,先创建权限一致的新 Key,更新 sub2api 上游账号,使用试点员工验证成功,再停用旧上游 Key。若旧 Key 已泄露,应优先撤销并处理受影响连接。

检查 Claude、GPT、Gemini 等多个上游记录是否复用了同一个旧 Key,避免只更新其中一处。员工始终使用企业网关个人 Key,一般无需随上游 Key 的正常轮换修改工具。

每周检查哪些内容

  • RootFlowAI 账户余额、上游 Key 有效期和所需模型权限。
  • sub2api 员工余额、异常增长的用量、失效或闲置的 Key。
  • 上游账号启用状态、限流、错误率与请求延迟。
  • 服务器磁盘、内存、CPU、数据库和备份占用。
  • HTTPS 证书有效期和自动续签结果。
  • 最近一次备份是否完成,以及最近一次恢复演练记录。

并发限制应结合上游允许量和服务器资源逐步调整。员工人数增加,不代表应等比例提高每人的并发。

创建一致的冷备份

下面的方法会短暂停止企业网关及其数据库、Redis,适合初期单机部署。提前通知员工,并确认没有必须持续运行的任务。备份包含上游 Key、密码、员工信息和日志,必须按企业敏感数据保管。

在服务器执行:

cd /opt/company-ai
sudo install -d -m 700 /opt/company-ai-backups
docker compose -f docker-compose.local.yml stop

停止成功后,打包整个部署目录,再启动原服务:

backup_file="/opt/company-ai-backups/company-ai-$(date +%Y%m%d-%H%M%S).tar.gz"
sudo tar --acls --xattrs -czpf "$backup_file" -C /opt company-ai
docker compose -f docker-compose.local.yml start
docker compose -f docker-compose.local.yml ps

即使打包失败,也应先运行 start 恢复服务,再处理备份问题。不要让一次失败的备份使服务持续停止。

检查归档可读取并生成校验值:

sudo tar -tzf "$backup_file" > /dev/null
sudo sha256sum "$backup_file"

本教程的数据目录为 data/、postgres_data/ 和 redis_data/,环境文件为 .env。完整保留它们及 Compose 文件;另外备份 Nginx 站点配置,并记录 DNS、证书恢复方式和所用镜像摘要。

保留至少一份加密的异机备份。同一台服务器上的备份不能覆盖整机故障;只看到压缩包存在,也不能代替恢复演练。

在隔离环境演练恢复

使用新的演练服务器,安装兼容的 Docker 和 Compose。确保没有名为 /opt/company-ai 的现有生产目录,也没有与配套容器名称冲突的服务,再复制备份并核对校验值。

以下命令中的备份文件名需要替换:

sudo tar --acls --xattrs -xzpf /path/to/company-ai-backup.tar.gz -C /opt
cd /opt/company-ai
docker compose -f docker-compose.local.yml config --quiet
docker compose -f docker-compose.local.yml up -d
docker compose -f docker-compose.local.yml ps

恢复会带回备份时的凭据和员工数据。演练环境先保持内部隔离,检查登录、用户、Key、历史用量和数据完整性;不要在尚未核对入口及上游配置时承接生产流量。

确认服务正常后,再为新环境配置对应域名、反向代理和证书。记录恢复耗时与缺失步骤,补充到企业运维手册。

升级前的操作顺序

  1. 阅读目标 release 的变更和数据库兼容说明,确定是否需要升级配套部署文件。
  2. 用现有版本完成备份,在隔离环境验证能够恢复。
  3. 在演练环境使用目标固定版本测试登录、员工授权、Key、余额、模型调用和流式输出。
  4. 记录应用镜像、Compose、数据库与 Redis 版本,安排生产维护窗口。
  5. 使用企业维护的升级脚本执行备份和升级;已有部署自带升级脚本时优先使用该脚本。
  6. 升级后核对健康、错误、用量和余额,再恢复正常使用。

不要把“拉取 latest 后重建容器”作为完整升级流程。数据库迁移后,旧应用镜像未必能直接兼容新数据库;需要回退时,应按已演练的应用、配置和数据库恢复方案执行。

更新页面或重新创建容器,不会自动备份数据;不要删除数据目录,也不要在保留数据的操作里使用删除卷的选项。

遇到异常查看常见问题排查。返回企业团队接入总览。