102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# 常见故障
|
||
|
||
## 1. 命令不存在
|
||
|
||
```bash
|
||
docker compose exec ai-tools ai-tools-check
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
```
|
||
|
||
如果只缺少一个命令，查看构建日志中对应 npm 包的安装错误。
|
||
|
||
## 2. 项目目录没有权限
|
||
|
||
在 Ubuntu 主机执行：
|
||
|
||
```bash
|
||
grep -E '^(AI_UID|AI_GID)=' .env
|
||
id -u
|
||
id -g
|
||
sudo chown -R "$(id -u):$(id -g)" /srv/projects
|
||
```
|
||
|
||
`.env` 中的 UID/GID 应与操作项目文件的 Ubuntu 用户一致。修改后重新构建容器。
|
||
|
||
## 3. 登录完成后重建容器又要求登录
|
||
|
||
检查持久化目录：
|
||
|
||
```bash
|
||
docker compose config
|
||
grep '^AI_HOME_PATH=' .env
|
||
ls -ld "$(grep '^AI_HOME_PATH=' .env | cut -d= -f2-)"
|
||
```
|
||
|
||
确认 Compose 仍把 `AI_HOME_PATH` 挂载到了 `/home/ai`，并且目录没有被手动删除。
|
||
|
||
## 4. Windows 运行脚本后界面显示异常
|
||
|
||
使用 Windows Terminal，并确保 SSH 分配终端：
|
||
|
||
```powershell
|
||
ssh -tt mobai@192.168.1.100 "docker exec -it ai-tools codex"
|
||
```
|
||
|
||
本部署包的 `remote-ai.ps1` 已经使用 `ssh -tt`。
|
||
|
||
## 5. 登录链接跳回 localhost 后失败
|
||
|
||
原因是网页在 Windows 打开，但登录回调服务在 Ubuntu 容器里。优先选择设备验证码登录或 API Key。只有在工具明确显示回调端口时，才建立对应的 SSH 端口转发。
|
||
|
||
不要直接把随机回调端口开放到公网。
|
||
|
||
## 6. 无法访问模型接口或 npm
|
||
|
||
在容器内检查 DNS 和 HTTPS：
|
||
|
||
```bash
|
||
docker compose exec ai-tools getent hosts registry.npmjs.org
|
||
docker compose exec ai-tools curl -I https://registry.npmjs.org/
|
||
```
|
||
|
||
如果 Ubuntu 主机需要代理，应把代理地址配置到 Docker daemon 或 Compose 环境中。代理凭证不要写入会提交的文件。
|
||
|
||
## 7. DeepSeek Harness 更新后参数变化
|
||
|
||
它目前是 developer preview。先查看当前帮助：
|
||
|
||
```bash
|
||
docker compose exec ai-tools dsh --help
|
||
docker compose exec ai-tools dsh web --help
|
||
```
|
||
|
||
确认工作后，把 `.env` 的 `DSH_VERSION` 从 `latest` 改为当前版本号并重新构建。
|
||
|
||
## 8. OpenClaw 受到影响
|
||
|
||
本 Compose 文件没有安装 OpenClaw、没有映射 OpenClaw 端口，也没有挂载 OpenClaw 配置目录。若现有 OpenClaw 出现问题，应单独检查它原来的服务，不要删除 AI 工具箱的 `data` 目录试图修复。
|
||
|
||
## 9. CC Switch 切换后没有生效
|
||
|
||
先检查冲突环境变量和当前 Provider：
|
||
|
||
```bash
|
||
ai cc-switch env check --app codex
|
||
ai cc-switch --app codex provider current
|
||
```
|
||
|
||
确认网页“设置 -> Provider”中的“CC Switch 配置接管”已启用，并重新创建 CLI 会话。已经运行中的会话不会自动切换 Provider。
|
||
|
||
## 10. Multica daemon 离线
|
||
|
||
```bash
|
||
ai multica config show
|
||
ai multica daemon status --output json
|
||
docker compose logs --tail=150 ai-tools
|
||
```
|
||
|
||
若 `workspace_id` 未设置，回到网页 Runtime 页面重新初始化。若配置完整但 daemon 未上线，执行 `docker compose restart ai-tools`，Supervisor 会重新拉起它。不要在容器内额外运行后台 daemon，否则会与 Supervisor 管理的前台进程重复。
|
||
|
||
若授权页面最终跳回无法访问的本地回调地址，使用部署文档“初始化 Multica Runtime”中的一次性 host 网络命令。它只负责写入 `/home/ai/.multica`，不会改变正式 Compose 的网络边界。
|