跳转至

安全与密钥

管理员账户

  • 管理员必须启用 TOTP；
  • 敏感操作 Step-up 2FA 建议开启；
  • 不创建无用途的管理员 API Key；
  • 管理员密码保存在可信密码管理器中。

所有成员看到什么

所有成员在客户端侧使用 YNumerics 用户侧 API Key。上游服务账号和上游服务凭据仅由管理员在后台维护，不需要写入 Codex++ 或普通 API 客户端配置。

这也是网关的意义之一：成员只连接 api.ynumerics.top，平台负责后续路由和上游认证。

Nginx 与真实客户端 IP

Nginx 是公网反向代理，Sub2API 仅监听本机 127.0.0.1:8080。

反向代理应覆盖而不是继承客户端伪造的 IP 头：

proxy_set_header CF-Connecting-IP $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;

公开注册与邮件验证码

当前公开注册需要复旦学邮 + 邮箱验证码 + 管理员邀请码。生产环境还应启用人机验证；邮箱白名单和邀请码不能替代验证码发送接口本身的抗滥用保护。

SMTP 使用专用邮箱 ynumerics_admin@163.com。SMTP 客户端授权码按生产密钥处理：只保存在 Sub2API 后台 / 可信密码管理器中，不写入文档、截图或群聊。

如果验证码邮件出现异常突增：

  1. 立即查看注册 / 验证码接口访问日志和来源 IP；
  2. 检查人机验证是否仍正常生效；
  3. 检查 Nginx / trusted proxies 是否会让客户端伪造真实 IP；
  4. 必要时临时关闭开放注册或邮箱验证发送入口；
  5. 检查 163 邮箱发件记录、退信和安全状态。

不应进入公开文档或公开聊天的敏感信息

  • /opt/sub2api/.env 的实际内容；
  • 上游服务凭据；
  • 用户个人 API Key；
  • SMTP 授权凭据；
  • TOTP Secret / 二维码；
  • PostgreSQL 密码；
  • JWT Secret；
  • SSH 私钥。

Key 泄露

发现某把用户 Key 出现在截图、聊天记录、Git 历史或日志中：

  1. 立即撤销旧 Key；
  2. 生成新 Key；
  3. 更新对应客户端；
  4. 查看使用记录是否有异常请求；
  5. 必要时暂停相关账号。

上游 cyber_policy 会话屏蔽

某个会话被上游网络安全策略 cyber_policy 拦截后，本地中转站会记录并屏蔽该会话，后续请求不再转发到上游。屏蔽范围只限该会话，不影响同一 Key 的其他会话。

排障时先区分“会话被屏蔽”和“Key / IP 被封禁”：

  • cyber_policy：新建符合策略的会话后，同一 Key 仍可使用；
  • Key 问题：通常影响该 Key 的全部会话；
  • IP 封禁：通常影响该公网 IP 对站点的访问。

成员报告疑似误判时，收集发生时间、模型、错误消息和 Request ID，不收集完整 Key 或会话中的敏感内容。

IP 封禁与误封处理

当前登录防护包括：

  • Fail2ban jail ynumerics-login：对重复登录失败进行临时、递增封禁；
  • Nginx 手工黑名单：/etc/nginx/snippets/ynumerics-blocked-ips.conf；
  • 邮箱陷阱自动永久黑名单：/etc/nginx/snippets/ynumerics-auto-sub2api-email-blocks.conf；
  • systemd timer ynumerics-sub2api-email-ban.timer 每分钟检查新增审计记录。

用户报告 IP 误封时，应先核验其注册邮箱、当前公网 IP、发生时间和日志。查看状态：

sudo fail2ban-client status ynumerics-login
sudo systemctl status ynumerics-sub2api-email-ban.timer --no-pager
sudo journalctl -t ynumerics-sub2api-email-ban -n 50 --no-pager

确认误封后，从手工和自动两个 Nginx 文件中删除对应的 deny IP;（如存在），再执行：

IP='203.0.113.10'  # 替换为确认误封的实际 IP
sudo nginx -t && sudo systemctl reload nginx
sudo fail2ban-client set ynumerics-login unbanip "$IP"

自动黑名单按审计 ID 增量处理，删除旧条目后不会因为旧日志立即重新封禁；但该 IP 以后再次触发邮箱陷阱时仍会重新进入黑名单。目前没有永久白名单机制。

用户密码重置

密码重置申请必须由注册账号对应的本人复旦学邮发送到 ynumerics_admin@163.com。核验姓名和平台注册邮箱后，在管理后台执行密码重置并回复后续步骤。

不要要求用户通过邮件发送旧密码、新密码、API Key 或验证码；管理员也不要在邮件中保存或转发用户密码。