162 lines
5.0 KiB
Markdown
162 lines
5.0 KiB
Markdown
# Docker 版 OpenClaw 部署飞书插件 - 难点总结
|
||
|
||
> 日期：2026-03-22
|
||
> 环境：macsvr（192.168.254.104），项目路径：`/home/macsvr/Work/dock-openclawd-ai/`
|
||
|
||
---
|
||
|
||
## 一、版本管理问题
|
||
|
||
### 问题
|
||
- Dockerfile 使用本地 `openclaw-dist/` 目录构建镜像，不会自动更新
|
||
- 更新 openclaw 需要：先 `npm pack openclaw` 更新 `openclaw-dist/`，再 `docker compose build --no-cache` 重新构建
|
||
|
||
### 解决方案
|
||
```bash
|
||
# 在 macsvr 上执行
|
||
cd /home/macsvr/Work/dock-openclawd-ai
|
||
npm pack openclaw --pack-destination .
|
||
tar xzf openclaw-*.tgz -C openclaw-dist/ --strip-components=1
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
```
|
||
|
||
### 注意
|
||
- 飞书插件 `@larksuite/openclaw-lark` 版本需 ≤ openclaw 版本，否则报 `Cannot find module` 错误
|
||
- 当前 npm 最新版：openclaw `2026.3.13`，飞书插件 `2026.3.18`（插件比主程序新，可能兼容性问题）
|
||
|
||
---
|
||
|
||
## 二、文件权限问题
|
||
|
||
### 问题
|
||
容器启动失败，报 `EACCES: permission denied, open '/usr/local/lib/node_modules/openclaw/openclaw.mjs'`
|
||
|
||
### 根因
|
||
Dockerfile 中 `COPY openclaw-dist/` 后用 `chown -R node:node` 修正权限，但如果 `openclaw-dist/` 目录内文件权限本身有问题（如 root 所属），构建后容器内 node 用户无法读取。
|
||
|
||
### 解决方案
|
||
重新 build 镜像（`--no-cache`）会重新执行 chown，通常可解决：
|
||
```bash
|
||
docker compose build --no-cache && docker compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Gateway Token 不一致
|
||
|
||
### 问题
|
||
`.env` 里的 `OPENCLAW_GATEWAY_TOKEN` 与 `data/config/openclaw.json` 里的 `gateway.auth.token` 不一致，导致：
|
||
- 健康检查持续 `token_mismatch`
|
||
- Control UI 无法连接
|
||
|
||
### 优先级
|
||
`OPENCLAW_GATEWAY_TOKEN` 环境变量 **优先于** config 文件中的 token。
|
||
|
||
### 解决方案
|
||
保持两者一致，推荐以 config 为准：
|
||
```bash
|
||
# 修改 .env
|
||
OPENCLAW_GATEWAY_TOKEN=openclaw_test_token
|
||
|
||
# 确认 config 中
|
||
# gateway.auth.token = "openclaw_test_token"
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Control UI 跨机器访问被拒
|
||
|
||
### 问题
|
||
从局域网其他机器浏览器访问 `http://192.168.254.104:20888`，报错：
|
||
- `origin not allowed`
|
||
- `control ui requires device identity (use HTTPS or localhost secure context)`
|
||
|
||
### 解决方案
|
||
在 `data/config/openclaw.json` 中配置：
|
||
```json
|
||
{
|
||
"gateway": {
|
||
"controlUi": {
|
||
"allowedOrigins": ["*"],
|
||
"allowInsecureAuth": true,
|
||
"dangerouslyDisableDeviceAuth": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> ⚠️ 仅限内网可信环境使用，生产环境应配置 HTTPS
|
||
|
||
---
|
||
|
||
## 五、飞书插件安装扫码流程无法在 SSH 中完成
|
||
|
||
### 问题
|
||
`npx @larksuite/openclaw-lark install` 需要交互式 TTY 显示二维码并等待扫码，但：
|
||
- SSH 会话超时断开 → 二维码消失
|
||
- `docker exec -it` 在非交互式 SSH 环境中不稳定
|
||
- tmux/screen 在容器内可用，但 session 管理复杂
|
||
|
||
### 根因
|
||
飞书扫码步骤需要持久 TTY + 人工操作，不适合远程自动化。
|
||
|
||
### 解决方案
|
||
**必须在 macsvr 本地终端直接运行：**
|
||
```bash
|
||
docker exec -it openclaw-gateway npx @larksuite/openclaw-lark install
|
||
```
|
||
或在 macsvr 桌面开终端执行，不要通过 SSH 远程跑。
|
||
|
||
---
|
||
|
||
## 六、Docker 重启后插件丢失
|
||
|
||
### 问题
|
||
在运行中的容器内安装飞书插件（写入容器层），`docker compose restart` 后插件消失。
|
||
|
||
### 根因
|
||
容器非持久化层在重启时被清空；只有挂载到 volume 的目录（`./data/config:/home/node/.openclaw`）才会保留。
|
||
|
||
### 解决方案
|
||
插件必须安装到 volume 挂载路径：
|
||
```bash
|
||
# 方法一：在 macsvr 宿主机直接解压到 volume 目录
|
||
npm pack @larksuite/openclaw-lark -D /tmp/
|
||
tar xzf /tmp/larksuite-openclaw-lark-*.tgz -C /tmp/lark-extract/
|
||
cp -r /tmp/lark-extract/package /home/macsvr/Work/dock-openclawd-ai/data/config/extensions/openclaw-lark
|
||
cd /home/macsvr/Work/dock-openclawd-ai/data/config/extensions/openclaw-lark
|
||
npm install --production
|
||
|
||
# 方法二：docker compose 中增加 extensions volume 挂载（推荐长期方案）
|
||
```
|
||
|
||
---
|
||
|
||
## 七、python3 依赖（tmpfs 导致重复安装）
|
||
|
||
### 问题
|
||
`npx @larksuite/openclaw-lark install` 需要 python3，但容器内 `/tmp` 挂载为 tmpfs（`docker-compose.yml` 配置），每次重启后 apt 缓存清空，需重装。
|
||
|
||
### 解决方案
|
||
**修改 Dockerfile**，在构建时预装 python3：
|
||
```dockerfile
|
||
RUN apt-get update && apt-get install -y python3 && rm -rf /var/lib/apt/lists/*
|
||
```
|
||
或者移除 docker-compose.yml 中的 tmpfs 配置（会增加容器层大小）。
|
||
|
||
---
|
||
|
||
## 最终结论
|
||
|
||
| 方案 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| npm 版 openclaw + 飞书 | ✅ 正常运行 | macsvr 本机，已配置飞书 appId，响应正常 |
|
||
| Docker 版 openclaw + 飞书 | ⏸ 暂缓 | 扫码配置流程需要本地终端，待后续补全 |
|
||
|
||
**Docker 版飞书配置的正确姿势（待操作）：**
|
||
1. Dockerfile 预装 python3
|
||
2. macsvr 本地终端跑 `docker exec -it openclaw-gateway npx @larksuite/openclaw-lark install`
|
||
3. 飞书扫码完成后 appId/appSecret 写入 `data/config/openclaw.json`
|
||
4. `docker compose restart` 使配置生效
|