换 shop-credential-key 会让 435 行历史密文全部解不开,而调用方拿到解不开的串 是当明文口令往外发(紫鸟账号、1688 店铺、第三方 api_key 都这样用)。 现在新增 aiimage.security.shop-credential-key-previous(逗号分隔),解密按 当前→历史的顺序回试,加密只用当前密钥;全部不中时 WARN 写明"这串密文会被 当成明文口令发出去",不再静默回退。与当前密钥相同的历史项自动丢弃。 previous 留空时行为与改动前逐字节一致(6 例单测盯着这一条)。 轮换设计与取证见 docs/ops/credential-rotation-design-2026-10-02.md(只含长度与 sha8 指纹,无明文值);轮换本身与存量重加密脚本仍未做。
8.9 KiB
店铺凭据密钥轮换设计(2026-10-02)
范围:aiimage.security.shop-credential-key 这一把密钥的轮换,以及轮换时三张库里凭据表怎么处理。
本文只给设计、取证结果和待办,没有执行过任何轮换或重启。
一、为什么现在不能直接换密钥
ShopCredentialCryptoService.decrypt() 解不出来时回退返回原文(ShopCredentialCryptoService.java:76-97)。
调用方拿到这串原文就当明文口令往外发——紫鸟账号、1688 店铺、第三方 api_key 都是这样被使用的。
所以「改了密钥、没重加密存量」这段时间里的表现不是报错,而是拿着密文当口令去登录,
失败点离原因很远,最难查。
本次改动(只做防护,未动线上):
ShopCredentialCryptoService支持shop-credential-key-previous(逗号分隔的旧密钥),解密时当前密钥失败后按顺序回试旧密钥,加密只用当前密钥。- 回退不再静默:打 WARN,写明「当前密钥 + N 个历史密钥都试过」,并直接说出后果(这串密文会被当成明文口令发出去)。
二、生效值到底配在哪一层(今天的实测)
| 键 | 位置 | 读数 |
|---|---|---|
shop-credential-key |
容器 /app/application-server.yml(宿主 /app/java/) |
configured=yes len=64 sha8=190cc85c occurrences=1,两台一致 |
jwt-secret |
同上 | len=64 sha8=2d40fe8a,两台一致 |
AIIMAGE_SHOP_CREDENTIAL_KEY |
宿主 /.env、java 进程 environ |
两处都没有 |
AIIMAGE_JWT_SECRET |
同上 | 两处都没有 |
AIIMAGE_DB_PASSWORD |
宿主 /.env(= java 进程 environ) |
len=16 sha8=83809acd,两台一致 |
结论:这两把密钥的生效值只有 yml 一个来源,没有环境变量覆盖它。 之前按「改 /.env 追加 export」的
配方去轮换这两把是无效的——那条配方只对 /.env 里真实存在的那些键有效。改密钥就改
/app/java/application-server.yml,两台各一份,改完 sha8 应当同步变化。
复现命令(只读,值不出生产):
MSYS2_ARG_CONV_EXCL='*' python scripts/_prod_config.py all --container java-server \
--file /app/application-server.yml --key shop-credential-key
三、存量行的形态:没有明文(本次实测)
scripts/_probe_credential_decrypt_audit.sh 在主机A 上用当前密钥真解了一遍三张表的七个凭据列,
只输出计数。判据与 Java 一致:AES/ECB/PKCS5Padding,密钥 = SHA-256(原文密钥) 前 16 字节;
并且必须过 base64 往返、16 字节对齐、填充合法、解出来是合法 UTF-8 四道关
——只看长度和对齐是不够的,换错密钥也能解出「看着像样」的字节。
| 表.列 | 行数 | 空 | 解得出 | b64 非串 | 长度不对 | 填充不对 | 非 UTF-8 |
|---|---|---|---|---|---|---|---|
biz_shop_manage.password |
86 | 0 | 86 | 0 | 0 | 0 | 0 |
biz_user_api_secret.secret_value |
314 | 0 | 314 | 0 | 0 | 0 | 0 |
biz_image_video_secret.copy_api_key |
7 | 0 | 7 | 0 | 0 | 0 | 0 |
biz_image_video_secret.t8_key |
7 | 0 | 7 | 0 | 0 | 0 | 0 |
biz_image_video_secret.t8_video_key |
7 | 2 | 5 | 0 | 0 | 0 | 0 |
biz_image_video_secret.voice_api_key |
7 | 0 | 7 | 0 | 0 | 0 | 0 |
biz_image_video_secret.voice_group_id |
7 | 0 | 7 | 0 | 0 | 0 | 0 |
三点用处:
- 没有明文行,435 行里 433 行是当前密钥解得出的密文,另 2 行是空值。所以重加密可以走纯 Java 一条路,不需要「遇到解不出的行就跳过」的分支——那个分支的存在本身就等于把密文当明文写回去。
- 轮换前跑一次、轮换后跑一次,
解得出的计数应当一模一样,这是这批改动的验收标准。 - 写入路径本来就全过加密(
ShopManageService.java:100,124、UserApiSecretService.java:843, 两处setSecretValue/setPassword都包着encrypt(...)),没有发现明文字段入口。
四、轮换顺序(每一步都能单独发版)
- 先发版:带双密钥回试的版本。此时
previous为空,行为与旧版逐字节相同 (behaves_exactly_as_before_when_previous_keys_is_empty钉住这条)。 - 改配置:两台
/app/java/application-server.yml同时改——shop-credential-key写新值、shop-credential-key-previous写旧值。这一步起新数据用新密钥加密,旧数据仍解得出。 回滚 = 把两行改回原值重启,比重加密便宜得多。 - 重加密存量:跑一次迁移(下面第 5 节),把这 433 行用当前密钥重新加密。
- 验证:再跑
scripts/_probe_credential_decrypt_audit.sh,解得出仍是 433、其余四类仍为 0。 - 收尾:清掉
shop-credential-key-previous,下次发版生效。留着不影响正确性,只是每次解密多一轮试。
顺序不能反:先改配置再发版的话,旧 jar 不认 previous 这个键,存量行立刻进回退分支。
五、重加密迁移的关键约束
- 只改密文,不改业务时间戳。 这批表上有
updated_at会被心跳/看板读,走实体更新会顺带刷新它。 - 不要走业务 Service 的写入路径(会带缓存刷新、索引重算、
ziniaoShopIndexRefreshTrigger之类的副作用)。 用一条独立的取行→解密→用当前密钥加密→按主键回写的脚本,跑在 Java 侧。 - 分表分批、每批独立事务;失败要能重跑(重加密天然幂等,重复跑只是再解一次)。
- 迁移脚本本次没写,等你定了窗口再动。
六、不该走这条路的几把密钥
| 密钥 | 为什么另算 |
|---|---|
auth.jwt-secret(sha8 2d40fe8a) |
换它 = 现有登录态全废,所有人被踢;必须单独定维护窗口,和重加密无关 |
AIIMAGE_DB_PASSWORD(sha8 83809acd) |
库口令,改它要同时动 /.env 与 MySQL 账号,属另一套流程 |
| 极客图 / jikip / LLM 代理 key | 生效值在 yml 或 biz_user_api_secret,前者按普通配置轮换、后者随第五节的迁移一起走 |
| MinIO(B 机设备日志、A 机业务桶) | 走各自的 .env/服务重启,与店铺凭据无关 |
七、验证做到哪一步
- 新增
ShopCredentialCryptoServiceTest6 条,mvn -o -Dtest=ShopCredentialCryptoServiceTest test→Tests run: 6, Failures: 0, Errors: 0+BUILD SUCCESS。 - 变异检验:把
candidates.addAll(previousKeySpecs)删掉后重跑 →Tests run: 6, Failures: 2(rotates_key_but_still_decrypts_legacy_ciphertext、tries_several_previous_keys_in_order变红), 说明这两条真的在钉双密钥回试,不是恒绿断言。 (Python 侧的等价做法见scripts/tests/:umask 077挪到base64 -d >之后、或绕过upload_and_run_command直接拼命令,各有 1 条用例变红,改完的文件按 md5 原样还原。) - 这批测试走的是标准生命周期(
mvn -o -Dtest=ShopCredentialCryptoServiceTest test)。 上午有一段时间test-compile被并发会话新加的未跟踪测试挡住,当时只能用「javac 单编我的测试类 +surefire:test单跑」绕过;09:5x 复跑时那条阻塞已经自己清了,没有动过别人的文件。 - Python 侧:
scripts/tests共 78 例(PYTHONUTF8=1 python -m pytest scripts/tests -q全绿)。 掩码层那 8 个护栏点也各打坏过一次(出口不掩码、三层各自失效、verdict把读不到当一致、裸标记不记录、MSYS 路径不拦、atexit没注册),8/8 都有用例变红;其中「atexit.register(_report)删掉」原本是漏网之鱼——直接调_report的用例看不见「没注册」这个状态,补了一条开子进程实跑的用例才咬住。
八、还欠什么
-
轮换本身没执行,新密钥由你定、yml 由你改(生产写操作按约定只交付命令,不代跑)。
-
重加密迁移脚本没写——第五节的约束已经定好,等窗口。
-
ShopManageService.java:260往 VO 写的是masked,读侧掩码是有的;日志侧这几把密钥有没有 别的出口,本次没审。 -
外观/货源的 LLM key 分组那部分结论来自之前的实测记录(一把 key 平均挂 9.5 个账号), 本次没复核,引它做决策前先重跑一遍当时的脚本。
-
两台
/tmp里躺着 48 个 644 权限的历史探针副本(主机A 36 个、主机B 12 个,其中 20 个含password|secret|token|api_key形式的行)——那是_ssh_bash.py加rm -f收尾之前几次会话留下的。 上传命令现在带umask 077,新副本落成 600,但旧的这 48 个还在,删除算生产改动,命令给你:python scripts/_ssh_bash.py a scripts/清理用临时脚本 # 或直接 MSYS2_ARG_CONV_EXCL='*' python scripts/_ssh_probe.py all 'rm -f /tmp/_run__*.sh; ls /tmp/_run__*.sh 2>/dev/null | wc -l'后面那条回读应当是
0。