# 接入 vault

xiangqin 服务端（部署在 epsilon）的所有敏感凭证走 [vault](https://agentaily-vault.pages.dev/) 声明式管理。**客户端 `xq` CLI 不需要 vault** —— 只有部署服务端才要。

## 为什么走 vault

- 无 SDK：`vault install` 产出 `.vault/secrets.json`，代码 `json.load` 即可，跨语言
- 声明式：项目根 `vault.json` 像 `package.json`，一眼看得到项目用了哪些凭证
- 只存当前值：凭证轮换后 `vault sync` 重拉

## vault.json（已随仓库入库）

```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 首次 / 凭证轮换后）

```bash
cd /opt/xiangqin
vault install                # 读 vault.json → 写 .vault/secrets.json + .env
systemctl restart xiangqin   # 重启读新凭证
```

## 代码怎么读

```python
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、支付宝网关）是**常量**，写在代码里：

```python
# 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 多一层间接。

## 凭证轮换

举例——支付宝私钥轮换：

```bash
# 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
```

## 相关

- [vault 文档](https://agentaily-vault.pages.dev/) —— 5 层抽象 / CLI 参考 / 安全模型
- [运维](../ops.md) —— 部署脚本怎么触发 `vault install`
