接入 vault¶
xiangqin 服务端（部署在 epsilon）的所有敏感凭证走 vault 声明式管理。客户端 xq CLI 不需要 vault —— 只有部署服务端才要。
为什么走 vault¶
- 无 SDK：
vault install产出.vault/secrets.json，代码json.load即可，跨语言 - 声明式：项目根
vault.json像package.json，一眼看得到项目用了哪些凭证 - 只存当前值：凭证轮换后
vault sync重拉
vault.json（已随仓库入库）¶
{
"$schema": "https://vault-cli.local/schemas/v3/vault-manifest.schema.json",
"project": "xiangqin",
"credentials": {
"aliyun": {
"slug": "aliyun-main",
"fields": ["access_key_id", "access_key_secret", "default_region"],
"purpose": "OSS 备份 + DNS 记录（主账号 AK）"
},
"aliyun_sms": {
"slug": "aliyun-power-app-ak",
"fields": ["access_key_id", "access_key_secret"],
"purpose": "注册短信验证码（RAM 子账号 AK，短信专用）"
},
"alipay": {
"slug": "alipay-kongxuanpin",
"fields": ["app_id", "app_private_key", "alipay_public_key"],
"purpose": "曝光付费（当面付）"
}
},
"resources": [
{ "ref": "aliyun/ecs/i-...", "purpose": "服务端 epsilon" },
{ "ref": "aliyun/oss/agentaily-backup-xiangqin-prod", "purpose": "每日备份" },
{ "ref": "alipay/openapi-app/...", "purpose": "支付应用" }
]
}
接入流程（epsilon 首次 / 凭证轮换后）¶
cd /opt/xiangqin
vault install # 读 vault.json → 写 .vault/secrets.json + .env
systemctl restart xiangqin # 重启读新凭证
代码怎么读¶
from xiangqin import credentials as creds
c = creds.get("aliyun_sms")
ak, sk = c["access_key_id"], c["access_key_secret"]
别名（aliyun_sms）是 vault.json 里的 key，和 vault 里的 slug（aliyun-power-app-ak）解耦。以后换 slug 不改代码。
常量 vs 凭证的边界¶
公开元数据（签名名、模板 ID、支付宝网关）是常量，写在代码里：
# src/xiangqin/sms/aliyun.py
SIGN_NAME = "杭州阿空智能科技"
TEMPLATE_CODE = "SMS_317151039"
# src/xiangqin/payment/alipay.py
ALIPAY_GATEWAY = "https://openapi.alipay.com/gateway.do"
理由：这些是阿里云 / 支付宝侧的公开标识，没有秘密性，不值得走 vault 多一层间接。
凭证轮换¶
举例——支付宝私钥轮换：
# 1. vault 里改
vault credential edit alipay-kongxuanpin
# → 编辑器改 app_private_key
# 2. epsilon 上重拉 + 重启
ssh root@112.124.27.213
cd /opt/xiangqin
vault install
systemctl restart xiangqin