> ## Content Index
> Fetch the complete content index at: https://isoziyuan.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# WBAPI：一行命令装起 wb2api 反代栈
- URL: https://isoziyuan.com/p/100170/
- Published: 2026-09-25T04:44:46.000Z
- Updated: 2026-09-25T05:31:12.000Z
- Description: yys9253462-gif/WBAPI 这个一键脚本在全新 Linux 服务器上一条命令装起整套 wb2api 反代栈（网关 + 面板 + Caddy + 证书 + HTTPS）。本文给出用法、命令行参数、自带的 6 个回归用例（110 项断言），并说明一个值得记的数据风险：换密码会清空面板里所有非 admin 用户与 API 密钥。
- Author: Isoziyuan
- Tags: 技术实战, WBAPI, workbuddy, 一键脚本

## 一句话

[yys9253462-gif/WBAPI](https://github.com/yys9253462-gif/WBAPI?ref=isoziyuan.com) 这个一键脚本在全新 Linux 服务器上一条命令装起整套 wb2api 反代栈（网关 + 面板 + Caddy + 证书 + HTTPS），**六轮实测 110 项断言全过**。

```bash
curl -fsSL https://isoziyuan.com/dl/workbuddy-deploy.sh | sudo bash -s -- --domain wb.example.com --auto
```

> 默认镜像在你名下（不可绕过），下载链接带 1 小时缓存，校验请加 `?t=$(date +%s)`。

## 装完之后会得到什么

| 服务                          | 宿主端口           | 镜像                                                        |
| --------------------------- | -------------- | --------------------------------------------------------- |
| workbuddy2api 网关（OpenAI 兼容） | 127.0.0.1:7863 | ghcr.io/yys9253462-gif/workbuddy2api:latest               |
| workbuddy-manager 面板        | 127.0.0.1:7864 | ghcr.io/yys9253462-gif/workbuddy-manager-multiarch:latest |

两容器共用一个 docker network（`wbnet`），**端口只绑 127.0.0.1**，管理面板藏在反代之后。

## 它会自动做的事

1\. 检测并按需安装 Docker / compose 插件 2\. 生成或沿用凭据（`<BASE_DIR>/.credentials`，0600）：上游 api\_key + 面板管理员密码 3\. `git clone` 两个上游仓库 → 生成 docker-compose.yml（**不本机编译**，小内存机器跑 Go 会 OOM） 4\. `docker compose up -d` 起两容器 5\. 健康检查（先 2 秒快探，再退避） 6\. 给了 `--domain` 还会：装 Caddy、配反代、自动签 Let's Encrypt、开外网 HTTPS

## 命令行

| 参数                   | 作用                   |
| -------------------- | -------------------- |
| \-d, --domain <域名>   | 面板域名（DNS 需先指到本机）     |
| \--api-domain <域名>   | 独立 API 域名，只暴露 /v1    |
| \-p, --password <密码> | 面板密码，≥8 位，不能含 " 或 \\ |
| \-a, --auto          | 全自动，不问问题             |
| \--base-dir <目录>     | 安装根目录，默认 /opt/wb2api |

可覆盖的环境变量：`WB2API_IMAGE`、`MANAGER_IMAGE`、`REPO_UP`、`REPO_MG`、`WB2API_PORT`、`MANAGER_PORT`、`NET_NAME`、`UP_NAME`、`MG_NAME`。

> **同一台机器跑第二套时必须用上面这五个**，否则会和正式部署抢名字/端口。

## 前置条件

- root 权限
- 给了 `--domain` 的话，DNS 需先指向本机（脚本会校验并打印要加的 A 记录）

Docker / python3 / git / Caddy / 证书**不用你管**，缺什么脚本自己装。

## 改了什么（六轮实测挖到的真问题）

**1\. 管理员密码校验形同虚设** —— 帮助里写「≥8 位」，向导里强制 ≥8 位，但 `--password` / `ADMIN_PASSWORD` / 已有 `.credentials` 三条路径**完全没校验**。实测：传 `abc` 静默接受（而面板挂 docker.sock）；传 `ab"cd#efgh` 生成 `WB_ADMIN_PASSWORD: "ab"cd#efgh"`，go-yaml 解析失败，面板起不来。**现在统一在凭据解析完成后兜底**，显式输入非法直接 die，已有凭据里的弱密码只 warn（不阻断重跑，避免把在跑的用户锁死）。

**2\. clone 失败只剩一句废话** —— `>/dev/null 2>&1` 把 git 原话吞了，只留「克隆失败」。现在原样打印并按关键字翻译：`could not read Username` → 「仓库不存在或私有且无凭据」；`Could not resolve host` → 「连不上 GitHub」。

**3\. 上次中断会留下克隆不了的残目录** —— Ctrl-C 后 `<BASE_DIR>/workbuddy2api` 是非 git 空壳，`git clone` 因「目录非空」失败且报错同样被吞。现在识别为中断残留，提示后移除再克隆。

**4\. Ubuntu 下版本行串味** —— `Docker version 29.1.3, build 29.1.3-0ubuntu3~24.04.2` 里的 `grep -oE '[0-9]+\.[0-9]+\.[0-9]+'` 一次匹配出 2\~3 段。加 `| head -1`。

**5\. 摘要里的机器画像是写死的** —— 结尾一直写「本机内存有限（906MB）」，那是当初针对日本那台机器的描述。换机器就报错误信息。改为动态读取。

**6\. 0 账号 unhealthy 说明只在中途出现** —— 「网关 0 账号 → /healthz 503 → docker ps 显示 unhealthy」原本只在流程中段提示一次。**现在兜进最终摘要**。

顺带：把过严的白名单（把 `#` `$` `!` 也拒了）改成只禁 `"` `\` 和不可见字符；`WbTest#2026nosp` 这种密码现在不会被误伤。

## 一个值得记的数据风险

**`--password` 触发的「密码变更」会清空面板里所有非 admin 用户 + 所有对外 API 密钥 + 现有会话签名 secret。**

面板只在「首启 + 没有 users.json」时才会读 `WB_ADMIN_PASSWORD`，换密码必然要 `docker rm + rm users.json + up -d` 让它 bootstrap。新容器从零生成 admin 用户表，旧表里其他人/密钥一律丢失（**包括面板 UI 里加的那些**）。所以「换密码」=「面板全员重置」。要保留其他用户的话，要么手动备份 `data/users.json` 后手工合并，要么改用面板 UI 改密码。

## 验证矩阵

仓库 `tests/` 下有 6 个回归用例，**都在目标机上以 root 跑，输出「通过 N 项，失败 M 项」且退出码 = 失败数**（可直接接 CI）。

| 用例  | 场景                                  | 断言    |
| --- | ----------------------------------- | ----- |
| t01 | 人为制造中断残目录 + 全新安装                    | 12/12 |
| t02 | 幂等重跑 + 域名绑定（HTTPS / 证书 / conf.d）    | 16/16 |
| t03 | clone 失败可见性 + 报错人话化 + 残留清理          | 13/13 |
| t04 | Ubuntu 24.04 跨发行版全链路（隔离端口）          | 16/16 |
| t05 | 参数与边界 + 管理员密码策略（不拉镜像，最快）            | 19/19 |
| t06 | 完整 E2E（带域名）+ 幂等重跑 + 密码生命周期（含实际登录验证） | 34/34 |

合计 **110/110**。想快速自检就只跑 t05（十几秒）。

## 跑一次看看

```bash
# 1) 把脚本放到目标机器
scp deploy-workbuddy.sh root@<你的服务器>:/root/dwb.sh

# 2) 跑（无域名，只在本机）
bash /root/dwb.sh --auto --password 'MySecret#2026'

# 3) 想跑全套回归测试，先把脚本传到目标机
#    tests/t05 不拉镜像，十几秒就能跑完，验证密码策略这些关键修复没回归
scp tests/t05_parameter_and_password_validation.sh root@<你的服务器>:/root/
ssh root@<你的服务器> "bash /root/t05_parameter_and_password_validation.sh"
```

跑完会打印：

```
  通过 19 项，失败 0 项
```

## 下载

- 私有仓（含补丁脚本、tests/、README）：[https://github.com/yys9253462-gif/WBAPI](https://github.com/yys9253462-gif/WBAPI?ref=isoziyuan.com)
- 分享版（一键命令用这个）：<https://isoziyuan.com/dl/workbuddy-deploy.sh>