add: docker openclaw feishu 部署难点总结

docker-openclaw-feishu-issues.md

@@ -0,0 +1,161 @@
+# 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` 使配置生效