group_fqcd_jr/开发文档/D3.8-模型密钥轮换与凭据安全操作手册-2026-09-20.md

D3.8 · 模型密钥轮换与凭据安全操作手册

体系编号：D3.8　·　域：三、现行权威·完整版与专项　·　编号体系见 D1.1 §4.0

编号：CS-OPS-2026-023　|　版本：v1.0　|　日期：2026-09-20　|　状态：现行（操作手册，答辩后当轮执行） 性质：操作手册（SOP） —— 回答「两把模型密钥已经在会话/文档里出现过明文，怎么安全地换掉、怎么证明换对了」。 配套：工具 group_fqcd_jr\tools\rotate_api_keys.py（本手册的唯一执行入口）；演示脚本 D2.5；答辩报告 D2.6 §10 第 4 项；会话留痕 D1.6 §4.35 第五节第 2 项与 §4.39。 🔴 铁律：任何文档、任何提交、任何截图都不落 key 值（含掩码全量、含片段）。本手册只写变量名与校验方法。

---

0. 一句话结论

控制台建新 key（人工，不可自动化）→ 跑一个脚本改 .env → 重启 API + Worker → 复核 → 再吊销旧 key。 核心风险不是「会不会改错一个变量」，而是同一个 key 在 .env 里有多个变量名：漏改一个，就会出现「入库成功但检索失败」这类没有任何报错的症状。

---

1. 为什么要轮换（触发条件）

#	事实
1	本项目的两把模型密钥（DashScope/Qwen 一把、DeepSeek 一把）在对话过程中出现过明文（用户于 2026-09-18 直接粘贴在会话里）
2	会话记录（D1.6 等）与全部文档从未写入 key 值（W12 入库前已做过全仓密钥扫描：真实密钥只出现在被 .gitignore 命中的 .env）
3	但「明文已在会话里出现过」本身就是凭据泄露事件 ⇒ 按泄露处置：轮换 + 吊销旧 key

轮换不等于改一行：改完之后系统必须仍然能工作，这要用第 4 步的复核来证明，而不是靠「密码改成功了」的直觉。

---

2. 轮换前的现状（2026-09-20 实测，只写变量名与长度）

2.1 .env 里的 5 个变量（group_fqcd_jr\.env，已被 .gitignore 命中，不入库）

变量名	实测长度	谁在读它（代码取证）
QWEN_API_KEY	115	🔴 model_endpoint_config.id=1 的 secret_ref = env:QWEN_API_KEY（检索侧向量化）；tools\load_knowledge_milvus.py:50（灌库侧）
QWEN_EMBEDDING_API_KEY	115	tools\configure_embedding_endpoint.py:92（仅在端点不存在时用于创建端点）
DASHSCOPE_API_KEY	115	app\service\promotion_image_service.py:28（推广素材配图，缺则降级不报错）
DEEPSEEK_API_KEY	35	🔴 model_endpoint_config.id=2 的 secret_ref = env:DEEPSEEK_API_KEY（生成/判定）；app\service\advisor_reason_service.py:145
OFFSITE_DEEPSEEK_API_KEY	35	app\service\offsite_document_recognition_adapter.py:610（场外文档识别）

📌 脚本侧另有一个变量名 DEEPSEEK_API_KEY_NL2SQL（nl2sql_yc.py:156 优先取它、缺省回退 DEEPSEEK_API_KEY）。当前 .env 未定义该变量 ⇒ 走回退，无需处理。

2.2 数据库侧：secret_ref 存的是变量名，不是值

id	endpoint_code	provider	model_name	secret_ref	status
1	knowledge-embedding-qwen-v3	qwen	text-embedding-v3	env:QWEN_API_KEY	active
2	deepseek-flash	deepseek	deepseek-chat	env:DEEPSEEK_API_KEY	active

⇒ 轮换只改 .env，不需要动 DB。（EnvironmentSecretResolver 在运行时按名字去环境变量取值。）

2.3 键值分组（这就是脚本存在的理由）

组	变量	必须满足
Qwen（DashScope）	QWEN_API_KEY / QWEN_EMBEDDING_API_KEY / DASHSCOPE_API_KEY	三个 = 同一个值（同源同一把千问 key）
DeepSeek	DEEPSEEK_API_KEY / OFFSITE_DEEPSEEK_API_KEY	两个 = 同一个值（场外识别复用同一把）

---

3. 五步流程

第 1 步 · 控制台建新 key（人工，不可自动化）

服务	入口	建什么
阿里云 DashScope（百炼）	控制台 → API-KEY 管理	新建一把 Qwen key（形如 sk-…，实测长度 115）
DeepSeek 开放平台	控制台 → API keys	新建一把 DeepSeek key（形如 sk-…，实测长度 35）

⚠️ 先不要吊销旧 key —— 旧的留作回退，直到第 4 步复核通过。

第 2 步 · 体检（不改任何文件，先看现状）

cd D:\桌面\金融\group_fqcd_jr
$env:PYTHONPATH='D:\桌面\金融\group_fqcd_jr'
& '.\.venv\Scripts\python.exe' tools\rotate_api_keys.py --check

期望输出（2026-09-20 实测即为此）：

· Qwen（DashScope）：
    QWEN_API_KEY               sk-ws-…(115 位)
    QWEN_EMBEDDING_API_KEY     sk-ws-…(115 位)
    DASHSCOPE_API_KEY          sk-ws-…(115 位)
    ✅ 同值且非空
· DeepSeek：
    DEEPSEEK_API_KEY           sk-e35…(35 位)
    OFFSITE_DEEPSEEK_API_KEY   sk-e35…(35 位)
    ✅ 同值且非空

出现 ❌ 有变量为空 或 ❌ 取值不一致 时先别轮换，先查清为什么（不一致本身就是缺陷）。

第 3 步 · 轮换（交互式，输入不回显）

& '.\.venv\Scripts\python.exe' tools\rotate_api_keys.py

脚本会：① 提示输入新的 Qwen key（getpass，不回显）；② 提示输入新的 DeepSeek key；③ 校验格式（sk- 前缀 + 长度下限），不通过则整体不写入；④ 备份 .env.bak-<时间戳>（已被 .gitignore 命中）；⑤ 把三个 Qwen 变量写成同一个值、两个 DeepSeek 变量写成同一个值；⑥ 只替换目标行，其余行（含注释、缩进、顺序）原样保留。

第 4 步 · 重启 + 复核（不做这步等于没换）

# 1) 先停 API 与 Worker（进程里还是旧 key）
Get-CimInstance Win32_Process -Filter "Name like '%python%'" | Where-Object { $_.CommandLine -match 'uvicorn app.main:app|app.worker' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
# 2) 再起（日志见 _http_api.log / _http_worker.log）
Start-Process -FilePath 'D:\桌面\金融\group_fqcd_jr\.venv\Scripts\python.exe' -ArgumentList '-m','uvicorn','app.main:app','--host','127.0.0.1','--port','8000','--log-level','warning' -WorkingDirectory 'D:\桌面\金融\group_fqcd_jr' -WindowStyle Hidden
Start-Process -FilePath 'D:\桌面\金融\group_fqcd_jr\.venv\Scripts\python.exe' -ArgumentList '-m','app.worker' -WorkingDirectory 'D:\桌面\金融\group_fqcd_jr' -WindowStyle Hidden

#	复核项	命令 / 判据
1	服务就绪	GET /internal/health/ready → {"status":"ready", ...}
2	全链路探针	_eval_harness\http_probe.py → 11/11 succeeded（含访客线 + 客户线 + 反诈/账户/代办/画像/费率/多轮）
3	一键自检	demo.ps1 -SkipStart -NoBrowser → 五项自检全过（其中第 2 项「向量库三集合可查」即检索侧向量化的真实证明）
4	行情链路	tools\sync_market_prices.py → 跑通（另证明外部 HTTP 出口正常）
5	检索侧单独验（可选）	发一句知识型问句（如「七日年化是什么意思」）必须走 E3 正常作答；若变成「答不上来」或转人工，就是 key 没配对

第 5 步 · 吊销旧 key（只在第 4 步全过之后）

回到两个控制台，把旧 key 删除/禁用。删除后建议再跑一次第 4 步的第 2 项（证明系统确实已不再依赖旧 key）。

---

4. 三个必须知道的坑

#	坑	症状	为什么
1	只改了 QWEN_API_KEY，漏改另两个	「入库成功 / 检索失败」，或旧 key 吊销后才炸	三个变量来自同一把 key 的三个变量名，被三处不同代码读取（§2.1）
2	只改了 DEEPSEEK_API_KEY，漏改 OFFSITE_DEEPSEEK_API_KEY	主链路正常，场外文档识别静默降级	场外适配器读的是另一个变量名（§2.1）
3	手改 .env 时带了 BOM / 改了编码 / 改了换行	第一个变量读不出来（后面的都正常）⇒ 症状诡异、难查	.env 是纯文本按行解析；脚本改写时保留原编码与原换行，就是为了防这一条

📌 补充坑：改完不重启。UVicorn / Worker 进程内的环境变量是启动时读入的，.env 改了但进程没重启 ⇒ 仍然用旧 key。

---

5. 回退方式

场景	怎么做
第 3 步写入后想撤回	用同目录的 .env.bak-<时间戳> 原样覆盖回去，然后重启 API + Worker
新 key 在控制台建错了 / 想作废	在控制台禁用新 key，再用备份回退
旧 key 已吊销、新 key 又不能用	只能回控制台再建一把 —— 所以第 5 步必须排在第 4 步之后

---

6. 与其它文档的关系（避免两处口径漂移）

文档	关系
D2.6 §10 第 4 项「两把 API key 轮换」	本手册是它的执行细则；该项状态已从「手工 4 步」改为「跑一个脚本（D3.8）」
D2.5 §1 五项自检	第 4 步复核复用其中的「向量库三集合可查」
D1.6 §4.39	本轮（W13）新增工具与本手册的会话留痕
group_fqcd_jr\docs\26-JWT密钥管理与轮换.md	讲的是 JWT 签名密钥，与本手册的模型 API key 是两回事（前者是自签自验，后者是外部服务凭据）

---

7. 如实声明（本手册的能力边界）

项	说明
不能自动化第 1 步 / 第 5 步	控制台建 key 与吊销 key 必须由你本人在浏览器操作（无 API 授权、也不应为此开授权）
本手册不记录任何 key 值	连掩码全量都不落 —— 掩码+长度对穷举无用，但片段会缩小搜索空间，故一并省略
--check 只能证明「一致且非空」	它不联网验证 key 是否有效；key 是否可用由第 4 步的真实链路证明
未覆盖	阿里云/DeepSeek 控制台的子账号与权限模型（本手册只处理主账号 key 轮换）；密钥托管系统（KMS/Vault）接入 —— 当前项目用 .env，未上密钥托管