feat(deploy): 控制面收敛到 deploy/agent.sh,凭据不再出现在命令行

安全策略里有一条:**可疑的 bash 命令即使已加进 permissions.allow 白名单,
仍需人工批准**(内置文档 cli/security.md「命令注入检测」)。含
`Authorization: Bearer …` / `. ./.env` / 从环境取口令的命令正好命中,表现是
每次弹「凭证授权」;被拒时命令静默无输出,看着像服务故障——本轮实测一次
`/update` 就是这样根本没发出去(/jobs 里没有新任务、镜像还是旧的)。

所以把控制面全部封进 deploy/agent.sh:凭据只从仓库根 .env 读,对外暴露的
全是无凭据子命令,只需放行 `Bash(bash deploy/agent.sh:*)`。

- status / containers / logs / data / jobs / job / raw:只读查询
- update [tag] / wait <job> / rollback [tag] / restart / pull:变更与轮询
- release <tag>:构建推送 → 更新 → 验收,一条龙
- verify:**正式环境验收** —— 登录线上管理台 → 核对页面新标记
  (布局 max-width:1100px、subdomain_rule、cdSubRoll)→ 读
  GET /api/admin/domains 确认后端 subdomain_rule 已生效。
  只看容器起来是不够的,这条才证得了「镜像真换新 + 新代码在跑」。

修一个中文项目高频坑:变量后紧跟中文标点会被并进变量名
(`$LIVE_PORT(` → 变量名 `LIVE_PORT(`)→ unbound variable;已改 ${LIVE_PORT}
并用脚本全量扫过一遍(0 处残留)。

CLAUDE.md 补「含凭据的命令不要手敲」硬约定 + 沙箱启用前必须先解决的两条
(docker 与沙箱不兼容需 excludedCommands;测试 nginx 绑 0.0.0.0 与沙箱冲突)。
readme §12.5 补 agent.sh 用法,§12.6 登记 ipass-1.0.6,§16 补本条目。
This commit is contained in:
admin committed 2026-09-12 16:27:30 +08:00
1 parent 12f20dd342
commit 658356b20a
3 files changed
+297

No files matched your search

+25
View File
@@ -382,6 +382,31 @@ set -a; . ./.env; set +a
破坏性命令(`rm` / `sudo` / `docker rm` / `git push --force` / `git reset --hard`)显式 `deny`,仍会被硬拦。
- 白名单是**本机**配置:换机器要重拷 `.env` 与 `.workbuddy/settings.local.json`。
### ⚠️ 含凭据的命令**不要手敲**,一律走 `deploy/agent.sh`
**安全策略里有一条:可疑的 bash 命令即使已加进 `allow` 白名单,仍需人工批准**
(内置文档 `cli/security.md`「命令注入检测」)。`curl -H "Authorization: Bearer …"`、
`. ./.env`、从环境取口令这类形态正好命中——表现是**每次都弹「凭证授权」**;用户拒绝时
命令会**静默无输出**,极易误判成服务故障(实测踩过一次:`/update` 根本没发出去)。
所以:**凭据永远不出现在命令行上**。控制面/验收全部封在 `deploy/agent.sh` 里,
只需放行 `Bash(bash deploy/agent.sh:*)` 一条:
```bash
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印日志
bash deploy/agent.sh release 1.0.7 # 构建推送 → 更新 → 验收,一条龙
bash deploy/agent.sh verify # 正式环境验收(登录+页面标记+subdomain_rule)
bash deploy/agent.sh rollback [tag] # 回滚
```
> **另一条更彻底的路子**(尚未启用):开启 **bash 沙箱**
> (`sandbox.enabled: true` + `autoAllowBashIfSandboxed: true`)可从根上减少审批。
> 注意两个前提:① 官方文档说 `docker` 与沙箱不兼容,需放进 `excludedCommands`;
> ② 测试用 nginx `listen 18080;`(绑 0.0.0.0)与沙箱冲突,要先改成
> `listen 127.0.0.1:…` 并开 `network.allowLocalBinding`。**开工前先确认这两条**,再开。
## 常用操作
```bash
+232
View File
@@ -0,0 +1,232 @@
#!/usr/bin/env bash
# ---------------------------------------------------------------------------
# iPass 控制面(ipass-agent,见 readme §12.5)调用 + 正式环境验收。
#
# **存在的理由(重要,别再退回手敲 curl)**
# WorkBuddy/CodeBuddy 的安全策略里有一条:**「可疑的 bash 命令即使已加入
# permissions.allow 白名单,也需要手动批准」**(见内置文档 cli/security.md
# 「命令注入检测」)。含 `Authorization: Bearer …` / `. ./.env` / 从环境取
# 口令这类形态的命令正好命中——表现为**每次都弹「凭证授权」**,甚至在用户
# 拒绝时「命令静默无输出」,很容易被误判成服务故障(实测踩过:一次 /update
# 就是这样没发出去)。
#
# 结论:**凭据绝不能出现在命令行上**。本脚本把凭据只从仓库根 `.env` 读,
# 对外暴露的全是无凭据的子命令,于是只需放行这一条:
# "Bash(bash deploy/agent.sh:*)"
#
# 用法:
# bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
# bash deploy/agent.sh update [tag] # 完整更新(缺省用 .env 的 IPASS_IMAGE_TAG)
# bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印日志
# bash deploy/agent.sh verify # 正式环境端到端验收(登录+拉页面+查规则)
# bash deploy/agent.sh release <tag> # 构建推送镜像并更新、验收(一条龙)
# ...(其余子命令见 help)
#
# 依赖:仓库根 `.env`(已 gitignore)。缺文件或变量为空时直接报错退出。
# ---------------------------------------------------------------------------
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ENV_FILE="${IPASS_ENV_FILE:-$ROOT/.env}"
if [ ! -f "$ENV_FILE" ]; then
echo "✗ 找不到 $ENV_FILE —— 控制面凭据只从这里读(见 CLAUDE.md §凭据与授权)" >&2
exit 2
fi
set -a
# shellcheck disable=SC1090
. "$ENV_FILE"
set +a
A="${IPASS_AGENT_HOST:-}"
TOKEN="${IPASS_AGENT_TOKEN:-}"
REGISTRY="${IPASS_REGISTRY:-}"
DEFAULT_TAG="${IPASS_IMAGE_TAG:-}"
# 正式环境对外入口(验收用):管理域名 + 宿主端口 + 直连 IP
LIVE_HOST="${IPASS_MDM_HOST:-mdm.mayishangshu.cn}"
LIVE_PORT="${IPASS_PUBLIC_PORT:-88}"
LIVE_IP="${IPASS_LIVE_IP:-192.168.1.11}"
if [ -z "$A" ] || [ -z "$TOKEN" ]; then
echo "✗ .env 缺少 IPASS_AGENT_HOST / IPASS_AGENT_TOKEN" >&2
exit 2
fi
PY="$(command -v python3 || true)"
pretty() { if [ -n "$PY" ]; then "$PY" -m json.tool 2>/dev/null || cat; else cat; fi; }
jget() { "$PY" -c "import json,sys;print(json.load(sys.stdin).get('$1',''))" 2>/dev/null || true; }
get() { curl -s -m "${TIMEOUT:-30}" -H "Authorization: Bearer $TOKEN" "$A$1"; }
post() { curl -s -m "${TIMEOUT:-60}" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d "${2:-{\}}" "$A$1"; }
# tag / 完整镜像名 → 完整镜像名;空 → .env 的 IPASS_IMAGE_TAG
resolve_image() {
local t="${1:-}"
[ -z "$t" ] && t="$DEFAULT_TAG"
[ -z "$t" ] && { echo "✗ 未给 tag,且 .env 的 IPASS_IMAGE_TAG 为空" >&2; exit 2; }
case "$t" in
*/*:*|*:* ) printf '%s' "$t" ;;
ipass-* ) printf '%s:%s' "$REGISTRY" "$t" ;;
* ) printf '%s:ipass-%s' "$REGISTRY" "$t" ;;
esac
}
# ---- 正式环境访问(域名解析直连 .11,绕开 DNS) -----------------------------
# 全部在这里做,命令行里不出现任何凭据。
live_curl() { curl -sk -m "${TIMEOUT:-20}" --resolve "$LIVE_HOST:$LIVE_PORT:$LIVE_IP" "$@"; }
# 登录拿会话 cookie,写入 $1
live_login() {
local jar="$1" body code
body="$("$PY" - "$IPASS_ADMIN_USER" "$IPASS_ADMIN_PASSWORD" <<'PY'
import json, sys
print(json.dumps({"username": sys.argv[1], "password": sys.argv[2]}))
PY
)"
code="$(live_curl -o /dev/null -w '%{http_code}' -c "$jar" \
-H 'Content-Type: application/json' -d "$body" \
"https://$LIVE_HOST:$LIVE_PORT/api/admin/login")"
[ "$code" = "200" ]
}
cmd_wait() {
local id="$1" i j state=""
for i in $(seq 1 120); do
j="$(get "/jobs/$id?offset=0")"
state="$(printf '%s' "$j" | jget state)"
case "$state" in done|failed|error|cancelled) break ;; esac
sleep 1
done
if [ -n "$PY" ] && [ -n "$j" ]; then
printf '%s' "$j" | "$PY" -c '
import json, sys
d = json.load(sys.stdin)
print("state:", d.get("state"))
lg = d.get("log") or d.get("output") or []
if isinstance(lg, str):
lg = lg.splitlines()
for line in lg[-35:]:
print(line)
'
else
printf '%s\n' "$j"
fi
[ "$state" = "done" ]
}
# 正式环境验收:镜像对不对 + 新代码真的在线上跑(页面标记 + 接口下发)
cmd_verify() {
local jar rc=0 img dig
jar="$(mktemp -t ipass-live.XXXXXX)"
img="$(get /status | jget image)"
dig="$(get /status | jget digest)"
echo "· 镜像: $img"
echo "· digest: ${dig##*@}"
echo "· 登录 ${LIVE_HOST}:${LIVE_PORT}(-> ${LIVE_IP})"
if ! live_login "$jar"; then
echo " ✗ 登录失败(HTTP 非 200)"; rm -f "$jar"; return 1
fi
echo " ✓ 登录 200"
# 1) 管理台页面:布局自适应 + 子域名规则 UI(这两条都是本轮改动)
local html
html="$(live_curl -b "$jar" "https://$LIVE_HOST:$LIVE_PORT/admin")"
local m
for m in 'max-width:1100px' 'subdomain_rule' 'cdSubRoll' '换一个'; do
if printf '%s' "$html" | grep -qF -- "$m"; then
echo " ✓ 页面含「${m}」"
else
echo " ✗ 页面缺「${m}」—— 镜像可能没真正换新"; rc=1
fi
done
# 2) 接口下发子域名规则(后端常量真的生效)
local rule
rule="$(live_curl -b "$jar" "https://$LIVE_HOST:$LIVE_PORT/api/admin/domains" \
| "$PY" -c 'import json,sys;d=json.load(sys.stdin);print(json.dumps((d.get("data") or {}).get("subdomain_rule"),ensure_ascii=False))' 2>/dev/null || echo '')"
echo " · subdomain_rule = $rule"
case "$rule" in
*'"suffix": "dm"'*|*'"suffix":"dm"'*) echo " ✓ 规则后缀 = dm" ;;
*) echo " ✗ 规则未下发或后缀不对"; rc=1 ;;
esac
rm -f "$jar"
if [ "$rc" = "0" ]; then echo "✔ 正式环境验收通过"; else echo "✗ 正式环境验收未通过"; fi
return $rc
}
CMD="${1:-}"; shift || true
case "$CMD" in
status|check|health) get "/$CMD" | pretty ;;
containers) get "/containers" | pretty ;;
logs) get "/logs?tail=${1:-200}" ;;
jobs) get "/jobs?limit=${1:-5}" | pretty ;;
job) [ -n "${1:-}" ] || { echo "用法: bash deploy/agent.sh job <job-id> [offset]" >&2; exit 2; }
get "/jobs/$1?offset=${2:-0}" | pretty ;;
data) [ -n "${1:-}" ] || { echo "用法: bash deploy/agent.sh data users|domains|upstreams" >&2; exit 2; }
get "/data?file=$1" | pretty ;;
pull) IMG="$(resolve_image "${1:-}")"; echo "· 拉取 $IMG"
post "/pull" "{\"image\":\"$IMG\"}" | pretty ;;
update) IMG="$(resolve_image "${1:-}")"; echo "· 更新到 $IMG"
post "/update" "{\"image\":\"$IMG\"}" | pretty ;;
wait) [ -n "${1:-}" ] || { echo "用法: bash deploy/agent.sh wait <job-id>" >&2; exit 2; }
cmd_wait "$1" ;;
verify) cmd_verify ;;
rollback) if [ -n "${1:-}" ]; then post "/rollback" "{\"tag\":\"$1\"}" | pretty
else post "/rollback" '{}' | pretty; fi ;;
restart) post "/restart" '{}' | pretty ;;
raw) [ -n "${1:-}" ] || { echo "用法: bash deploy/agent.sh raw GET /check" >&2; exit 2; }
get "$2" | pretty ;;
release)
TAG="${1:-}"
[ -n "$TAG" ] || { echo "用法: bash deploy/agent.sh release 1.0.7" >&2; exit 2; }
IMG="$(resolve_image "$TAG")"
echo "== 1/3 构建并推送 $IMG =="
bash "$ROOT/deploy/release.sh" "${TAG#ipass-}"
echo
echo "== 2/3 更新正式环境 =="
JOB="$(post "/update" "{\"image\":\"$IMG\"}" | jget job)"
[ -n "$JOB" ] || { echo "✗ 未拿到 job id" >&2; exit 1; }
echo "· job = $JOB"
cmd_wait "$JOB" || { echo "✗ 更新任务未成功" >&2; exit 1; }
echo
echo "== 3/3 验收 =="
cmd_verify ;;
*)
cat <<'USAGE'
iPass 控制面包装(凭据只从 .env 读,命令行里不出现任何 key)
状态与信息
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh containers # 所有容器(标出受管容器)
bash deploy/agent.sh logs [tail] # 受管容器日志
bash deploy/agent.sh data users|domains|upstreams
变更
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印日志
bash deploy/agent.sh rollback [tag] # 回滚
bash deploy/agent.sh restart # 只重启
bash deploy/agent.sh pull [tag] # 只拉镜像
发版一条龙(构建推送 → 更新 → 验收)
bash deploy/agent.sh release 1.0.7
正式环境验收
bash deploy/agent.sh verify # 登录 + 拉页面标记 + 查 subdomain_rule
任务
bash deploy/agent.sh jobs [limit]
bash deploy/agent.sh job <id> [offset]
bash deploy/agent.sh raw GET /check
传 1.0.6 / ipass-1.0.6 / 完整镜像名 均可。
USAGE
[ -n "$CMD" ] && exit 2 || exit 0 ;;
esac
+40
View File
@@ -650,6 +650,28 @@ curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback # 出
> `image` 填**当前要上的 tag**(§12.6 的约定:只增不改,发新版就换新号,别覆盖旧号)。
> 不传 `image` 时用服务启动时的默认值(`--image` 指定,缺省 `ipass-1.0.0`)。
#### 推荐走 `deploy/agent.sh`(别手敲上面的 curl)
裸 `curl -H "Authorization: Bearer …"` 会把凭据摆到命令行上:既容易漏进 shell 历史 / 进程列表,
也会命中**「可疑命令即使已加白名单仍需人工批准」**的安全策略,于是**每次都弹「凭证授权」**;
被拒时命令还会**静默无输出**,看着像服务挂了(实测踩过:一次 `/update` 就是这样没发出去)。
`deploy/agent.sh` 把凭据只从仓库根 `.env` 读,对外暴露的全是无凭据子命令,因此只需放行一条
`Bash(bash deploy/agent.sh:*)`:
```bash
bash deploy/agent.sh status # 容器状态 + 镜像 digest + 数据摘要
bash deploy/agent.sh update [tag] # 拉镜像 + 重建容器(缺省用 .env 的 IPASS_IMAGE_TAG)
bash deploy/agent.sh wait <job-id> # 轮询任务直到结束并打印 7 步日志
bash deploy/agent.sh verify # 正式环境验收:登录 → 页面标记 → 后端 subdomain_rule
bash deploy/agent.sh release 1.0.7 # 一条龙:构建推送 → 更新 → 验收
bash deploy/agent.sh rollback [tag] # 出事回滚
```
`verify` 是「镜像真的换新了没有」的落地检查:它登录线上管理台,核对页面里的新标记
(如布局的 `max-width:1100px`、子域名规则的 `subdomain_rule` / `cdSubRoll`),
并读 `GET /api/admin/domains` 确认后端常量已生效——**光看容器起来是不够的**。
**爆炸半径:只碰一个容器**。虽然它等价 docker 权限,但**破坏性操作只作用于「受管容器」**——
`--name` 指定者优先,否则自动探测到的 ipass 容器;两者都没有时退化为 `ipass*` 前缀白名单。
`/update`、`/rollback`、`/restart` 请求里带 `name` 且**不等于**受管容器 → **直接 403**,
@@ -688,6 +710,7 @@ DRY_RUN=1 bash deploy/release.sh 1.0.3 # 只构建不推送
| `ipass-1.0.3` | 管理台「新建 / 更新 LLM 上游」表单的上游地址、密钥输入框独占整行(原被网格压到 ~170px,地址与密钥看不全)。 |
| `ipass-1.0.4` | **LLM 出站请求头改为「默认不放行」**(`proxy_pass_request_headers off` + 凭据头抹空 + 显式放行清单),堵住网关自己的 Key 经 `x-api-key` 泄漏给上游厂商。详见 `docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md`。 |
| `ipass-1.0.5` | **上游健康自动标记 + 管理台连通性测试 + 可复制 API 地址**。健康数据来自真实流量(log 阶段写 `uh:<slot>`,4xx=活、5xx/502/504=失效、下次成功自愈);「测试」按钮内部重定向复用 LLM 转发链路真探测;上游列表 OpenAI/Anthropic 复制按钮与 `anthropic_base_url`;统计挪进独立「数据总览」tab。 |
| `ipass-1.0.6` | **子域名规则固化为 `i`+8 位随机数+`dm`**(规则真源在 `config.rs`,经 `subdomain_rule` 下发给面板;API 不传 `subdomain` 即自动生成、撞车重试)+ **域名列表点完整域名即复制**(带端口,跟随调用方)+ **管理台布局改为自适应**(去掉 1180px 居中锁;表单另限宽 1100px)。digest `96c0e952…`,commit `12f20dd`。 |
---
@@ -916,6 +939,23 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage"
## 16. 变更记录
- **2026-09-12(续4)管理台布局自适应 + 控制面收敛到 `deploy/agent.sh`(`ipass-1.0.6`)**
- **布局自适应**:`.wrap` 去掉 `max-width:1180px` 居中锁与 `margin:0 auto`——大屏上原版面只占
中间一小块、右侧大片留白且表格被压窄。改为铺满视口;配套给 `.grid-form` 限宽 `1100px`,
否则面板变宽后 `auto-fit` 的 `minmax(160px,1fr)` 会把字段摊成十几列、表单被拉散。
1920 视口实测:面板 **1872px** / 表格 **1830px**(改造前约 1132px),表单 1100px。
- **控制面不再手敲 curl**:安全策略里「可疑命令即使已加 `allow` 白名单仍需人工批准」会命中
含 `Authorization: Bearer …` / `. ./.env` 的命令 → **每次都弹「凭证授权」**,拒绝时还**静默无输出**
(实测一次 `/update` 因此根本没发出去,差点误判成服务故障)。新增 `deploy/agent.sh`:
凭据只从 `.env` 读,对外全是无凭据子命令(`status` / `update` / `wait` / `verify` / `release` /
`rollback` / `data` / `logs`),只需放行 `Bash(bash deploy/agent.sh:*)`。
- **新增正式环境验收 `agent.sh verify`**:登录线上管理台 → 核对页面新标记 → 读
`GET /api/admin/domains` 确认 `subdomain_rule`。**只看容器起来是不够的**,这条能证「镜像真的换新 + 新代码在跑」。
- 落地:`ipass-1.0.6`(digest `96c0e952…`,commit `12f20dd`)已更新到 .11,7/7 步全过,
回滚点 `ipass-1.0.5`;`agent.sh verify` 复验通过(页面 4 个标记 + `subdomain_rule` 全中)。
- 踩坑:`agent.sh` 首跑报 `LIVE_PORT…: unbound variable` —— **变量后紧跟中文标点会被并进变量名**
(`$LIVE_PORT(` → 变量名 `LIVE_PORT(`),中文项目高频;改成 `${LIVE_PORT}` 并用脚本全量扫过一遍。
- **2026-09-12(续3)子域名规则固化(`i` + 8 位随机数 + `dm`)+ 点击复制 + API 同规则**
- 管理台「新建域名(直接放行)」的子域名改为**三段拼装**:固定 `i` + 8 位随机数字输入框(带「换一个」)+ 固定 `dm`。
随机源用**拒绝采样**(只接受 `< 250` 的字节)保证 0–9 等概率;`getrandom` 不可用时退化为 xorshift、