100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# Agent Secret Vault
|
||
|
||
本 repo 專門管理本地 AI agent / worker 需要的機密資料。
|
||
|
||
## 核心設計
|
||
|
||
- 使用 `ansible-vault` 加密 `secrets/vault.yml`
|
||
- 加密後的 `secrets/vault.yml` 可以進 git
|
||
- vault password file 放在本機：`~/.config/vault-pass.txt`
|
||
- 新機器可透過 repo 內的密碼保護壓縮檔 `secrets/vault-pass.txt.zip` 安裝 password file
|
||
- 多個 agent 透過統一腳本讀取 secrets，不各自發明 credential 管理方式
|
||
|
||
## 主要文件
|
||
|
||
- 人類使用指南：[`docs/human-guide.md`](docs/human-guide.md)
|
||
- Agent 安裝 Runbook：[`docs/agent-install-runbook.md`](docs/agent-install-runbook.md)
|
||
- Agent 整合補充：[`docs/agent-integration.md`](docs/agent-integration.md)
|
||
- Vault 基礎說明：[`docs/secret-vault.md`](docs/secret-vault.md)
|
||
|
||
## 安裝設定檔
|
||
|
||
Repo 內提供：
|
||
|
||
- `install.env.example`：給人類/agent 複製參考
|
||
- `install.env`：空值 placeholder；安裝前先填入 vault-pass 來源設定
|
||
|
||
常用變數說明：
|
||
|
||
| 變數 | 用途 | 範例 |
|
||
|---|---|---|
|
||
| `VAULT_PASS_FILE` | 最後要產生/使用的 vault password file 路徑 | `$HOME/.config/vault-pass.txt` |
|
||
| `INSTALL_VAULT_PASS_METHOD` | 指定安裝方式；可填 `create`、`manual`、`url`、`archive` | `url` |
|
||
| `VAULT_PASS_URL` | 當 method=`url` 時，從這個 URL 下載 `vault-pass.txt` | `https://example.com/one-time/vault-pass.txt` |
|
||
| `VAULT_PASS_ZIP_PASSWORD_FILE` | 當 method=`archive` 時，讀取 zip 密碼的本機檔案路徑；比直接寫密碼安全 | `/secure/path/zip-password.txt` |
|
||
| `VAULT_PASS_ZIP_PASSWORD` | 當 method=`archive` 時，直接提供 zip 密碼；只適合安全 shell，不建議寫進可提交檔案 | `...` |
|
||
| `VAULT_PASS_CONTENT` | 當 method=`manual` 時，直接提供 `vault-pass.txt` 內容；高風險，只適合受控環境 | `...` |
|
||
| `VAULT_PASS_ARCHIVE` | 覆寫密碼保護 zip 的路徑；預設是 `secrets/vault-pass.txt.zip` | `/path/to/vault-pass.txt.zip` |
|
||
|
||
安裝方式含義：
|
||
|
||
- `create`：產生新的 vault password；只適合全新 vault，既有 vault 無法解密時不會自動覆蓋。
|
||
- `manual`：由人類輸入或用 `VAULT_PASS_CONTENT` 提供 vault password 內容。
|
||
- `url`：從 `VAULT_PASS_URL` 下載 `vault-pass.txt`；適合一次性 URL / 內網安全下載。
|
||
- `archive`：從密碼保護 zip 解出 `vault-pass.txt`；密碼可放在 `VAULT_PASS_ZIP_PASSWORD_FILE` 或 `VAULT_PASS_ZIP_PASSWORD`。
|
||
|
||
`install.env` 不應填入真實 secrets 後再 commit；若要保存本機私密設定，使用 `install.local.env` 並透過 `INSTALL_ENV_FILE=install.local.env` 指定。
|
||
|
||
## 安裝流程（先設定 env）
|
||
|
||
安裝前請先設定 `install.env`，再檢查 env 是否足夠，最後才正式安裝：
|
||
|
||
```bash
|
||
cp -n install.env.example install.env
|
||
editor install.env
|
||
./scripts/install-vault-pass.sh --check-env
|
||
./scripts/install-vault-pass.sh
|
||
```
|
||
|
||
`install.env` 範例：
|
||
|
||
```bash
|
||
# 例：用一次性 URL 安裝 vault-pass.txt
|
||
INSTALL_VAULT_PASS_METHOD="url"
|
||
VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt"
|
||
```
|
||
|
||
## 全自動 agent 安裝
|
||
|
||
Agent / CI 也應優先設定 `install.env` 或 `INSTALL_ENV_FILE`，不要直接進互動選單：
|
||
|
||
```bash
|
||
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
|
||
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh
|
||
```
|
||
|
||
## 常用指令
|
||
|
||
```bash
|
||
# 安裝 vault password file（會要求輸入壓縮檔密碼）
|
||
./scripts/install-vault-pass.sh
|
||
|
||
# 維護者建立密碼保護壓縮檔
|
||
./scripts/create-vault-pass-archive.sh
|
||
|
||
# 檢視 vault
|
||
./scripts/vault.sh view
|
||
|
||
# 編輯 vault
|
||
./scripts/vault.sh edit
|
||
|
||
# 讀單一 secret
|
||
./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
|
||
```
|
||
|
||
## 安全原則
|
||
|
||
- 不要把 `~/.config/vault-pass.txt` commit 到 git
|
||
- 不要把解密後完整 YAML 貼到 chat/log
|
||
- Agent 回報時只回報 key path、commit hash、驗證方式，不回報 secret value
|