162 lines
4.7 KiB
Markdown
162 lines
4.7 KiB
Markdown
# 部署说明
|
||
|
||
## 1. 部署前提
|
||
|
||
Ubuntu 主机需要满足：
|
||
|
||
- Ubuntu 22.04 或 24.04，x86_64 或 ARM64
|
||
- 已安装 Docker Engine 和 Docker Compose Plugin
|
||
- 能访问各 CLI 的官网、npm Registry 和模型接口
|
||
- 当前用户有运行 Docker 的权限
|
||
- 建议至少 4 核 CPU、8 GB 内存和 15 GB 可用磁盘
|
||
|
||
这些 CLI 通常调用云端模型，本容器不在本机加载大模型权重，因此一般不需要 GPU。
|
||
|
||
## 2. 放置部署文件
|
||
|
||
建议把本目录放到 Ubuntu：
|
||
|
||
```text
|
||
/opt/ai-toolbox
|
||
```
|
||
|
||
项目统一放到：
|
||
|
||
```text
|
||
/srv/projects
|
||
```
|
||
|
||
创建项目目录：
|
||
|
||
```bash
|
||
sudo mkdir -p /srv/projects
|
||
sudo chown -R "$(id -u):$(id -g)" /srv/projects
|
||
```
|
||
|
||
## 3. 准备配置
|
||
|
||
```bash
|
||
cd /opt/ai-toolbox
|
||
cp .env.example .env
|
||
chmod +x scripts/ai
|
||
id -u
|
||
id -g
|
||
```
|
||
|
||
把 `id -u` 和 `id -g` 的结果填写进 `.env`：
|
||
|
||
```dotenv
|
||
WORKSPACE_PATH=/srv/projects
|
||
AI_HOME_PATH=/opt/ai-toolbox/data
|
||
AI_UID=1000
|
||
AI_GID=1000
|
||
AI_CONTAINER_NAME=ai-tools
|
||
TZ=Asia/Shanghai
|
||
```
|
||
|
||
不要把 API Key 写进 Dockerfile。`.env` 也不要提交到 Git。
|
||
|
||
## 4. 构建并启动
|
||
|
||
```bash
|
||
docker compose build
|
||
docker compose up -d
|
||
docker compose ps
|
||
docker compose exec ai-tools ai-tools-check
|
||
```
|
||
|
||
检查结果中以下命令都应显示 `OK`：
|
||
|
||
```text
|
||
codex claude codebuddy kimi opencode qwen dsh cc-switch multica
|
||
```
|
||
|
||
## 5. 首次登录
|
||
|
||
每个工具需要分别登录一次：
|
||
|
||
```bash
|
||
./scripts/ai codex .
|
||
./scripts/ai claude .
|
||
./scripts/ai codebuddy .
|
||
./scripts/ai kimi .
|
||
./scripts/ai opencode .
|
||
./scripts/ai qwen .
|
||
```
|
||
|
||
按照终端显示的链接或验证码，在 Windows 浏览器中完成登录。Kimi 进入界面后使用 `/login`。
|
||
|
||
远程服务器上，浏览器自动打开通常不会成功，这是正常的。优先使用工具提供的设备验证码登录；如果某个工具只支持浏览器回调，可以改用它支持的 API Key，或者为回调端口建立 SSH 隧道。
|
||
|
||
登录信息和会话文件保存在 `.env` 的 `AI_HOME_PATH` 目录中，不会因为重新构建镜像而丢失。
|
||
|
||
## 6. 初始化 CC Switch
|
||
|
||
打开网页的“设置 -> Provider”，点击“打开 CC Switch TUI”。先为 Claude、Codex 和 OpenCode 导入或创建 Provider，并确认三个 CLI 都有当前 Provider。
|
||
|
||
也可以在 SSH 中操作：
|
||
|
||
```bash
|
||
ai cc-switch
|
||
ai cc-switch --app codex provider list
|
||
```
|
||
|
||
配置完成后，在网页启用“CC Switch 配置接管”。启用后，AgentDock 不再向 Claude、Codex 和 OpenCode 会话注入网页账号页保存的旧 API Key，避免环境变量覆盖 CC Switch 配置。CodeBuddy、Kimi、Qwen 和 DeepSeek 仍由 AgentDock 管理。
|
||
|
||
## 7. 初始化 Multica Runtime
|
||
|
||
打开网页的“设置 -> Runtime”，填写现有自托管 Multica 的 Server URL 和 App URL，然后点击“初始化 Runtime”。授权只在独立终端中进行，完成后 Supervisor 会自动启动前台 daemon。
|
||
|
||
也可以在 SSH 中检查：
|
||
|
||
```bash
|
||
ai multica config show
|
||
ai multica daemon status --output json
|
||
docker compose logs --tail=100 ai-tools
|
||
```
|
||
|
||
Multica 当前公开支持 Claude、Codex、CodeBuddy、Kimi 和 OpenCode。Qwen 与 DeepSeek 会显示为“已安装，待验证支持”。本部署仅安装 Multica 客户端 Runtime，不包含也不替换用户现有的自托管服务端。
|
||
|
||
如果网页终端中的 OAuth 回调无法从 Windows 返回容器，可在 NAS SSH 中运行一次临时初始化。将两个示例 URL 替换为实际地址：
|
||
|
||
```bash
|
||
docker run --rm -it \
|
||
--network host \
|
||
--user 1000:1001 \
|
||
-e HOME=/home/ai \
|
||
-v /vol1/1000/docker/ai-toools/data:/home/ai \
|
||
local/ai-toolbox:0.2.0 \
|
||
multica-setup \
|
||
--server-url https://multica-api.example.com \
|
||
--app-url https://multica.example.com \
|
||
--callback-host 192.168.200.36
|
||
```
|
||
|
||
该容器只在授权期间使用宿主机网络，完成后自动退出。正式 Multica daemon 仍由 `ai-tools` 内的 Supervisor 管理，不使用 host 网络。
|
||
|
||
## 8. DeepSeek Harness
|
||
|
||
DeepSeek Harness 的命令是 `dsh`，当前属于 developer preview，官方提示未来可能出现不兼容更新。
|
||
|
||
无界面执行一次任务：
|
||
|
||
```bash
|
||
./scripts/ai dsh my-project --profile headless "检查项目并运行测试"
|
||
```
|
||
|
||
查看当前版本支持的参数：
|
||
|
||
```bash
|
||
docker compose exec ai-tools dsh --help
|
||
```
|
||
|
||
当前 npm 包只提供 `headless` 与 `web` profile，没有可安装的原生 TUI。AgentDock 使用 `headless`，每次提交一个任务，完成后进程自动退出。`web` profile 不纳入 Compose，也不额外暴露端口。
|
||
|
||
## 9. OpenClaw 和 Cursor
|
||
|
||
- 不修改 Ubuntu 主机现有的 OpenClaw。
|
||
- 不占用 OpenClaw 的 Gateway 端口。
|
||
- Cursor 桌面版保留在 Windows。
|
||
- Cursor 使用 Remote SSH 打开 `/srv/projects/项目名`。
|
||
- AI 容器通过 `/workspace/项目名` 访问同一批文件。
|