Opencode 飞牛 NAS (FnOS) 部署指南
本文档记录了在飞牛 NAS (FnOS) 上通过 Docker 部署 Opencode AI 编程助手的完整流程，包含踩坑记录与最终解决方案。
1. 准备工作
在 NAS 终端（SSH）中创建必要的配置与数据目录：
mkdir -p /vol1/1000/docker/opencode/config
mkdir -p /vol1/1000/docker/opencode/workspace
/config: 持久化存储 LLM 密钥、用户设置。/workspace: 存放你的代码项目，AI 将直接编辑此目录下的文件。
2. Docker Compose 配置 (最终修正版)
路径：/vol1/1000/docker/opencode/docker-compose.yml
核心修复点：
- 使用
entrypoint 覆盖默认启动命令。
- 必须使用
--hostname 0.0.0.0 而非 --host，否则容器会无限重启。
- 去掉了
tty: true 以适应 Web 服务模式。
version: '3.8'
services:
opencode:
image: ghcr.io/anomalyco/opencode:latest
container_name: opencode
restart: unless-stopped
# 强制以 Web 模式启动
# 注意：必须用 --hostname，旧版文档中的 --host 会导致参数解析失败
entrypoint: ["opencode", "web", "--hostname", "0.0.0.0", "--port", "3000"]
ports:
# 外部访问端口 3004 -> 容器内部端口 3000
- "3004:3000"
volumes:
- /vol1/1000/docker/opencode/config:/root/.opencode
- /vol1/1000/docker/opencode/workspace:/workspace
environment:
- WORKDIR=/workspace
# 国内 npm 加速
- NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
# 设置 Git 用户信息，防止 AI 提交代码时报错
- GIT_AUTHOR_NAME=opencode
- GIT_AUTHOR_EMAIL=bot@opencode.ai
# 如果 NAS 需要代理访问 OpenAI/Google，请取消注释以下行
# - HTTP_PROXY=http://192.168.x.x:7890
# - HTTPS_PROXY=http://192.168.x.x:7890
networks:
- opencode_net
networks:
opencode_net:
driver: bridge
3. 启动服务
cd /vol1/1000/docker/opencode
docker compose down # 如果有旧容器，先删除
docker compose up -d # 启动
4. 常见问题与排错
Q1: 容器无限重启，日志显示 ASCII 字符乱跳或 Help 信息
原因：启动参数错误。
解决：确保 docker-compose.yml 中使用的是 --hostname 0.0.0.0。旧版本或部分文档误写为 --host 会导致程序无法识别参数而退出。
Q2: 无法进入容器终端 (exec failed: "bash" not found)
原因：Opencode 镜像基于 Alpine 或精简版 Linux，未安装 bash。
解决：使用 sh 代替 bash。
docker exec -it opencode sh
Q3: 浏览器无法访问
原因：
- 端口映射错误（检查 NAS 防火墙是否放行 3004）。
- 服务监听在 127.0.0.1 而非 0.0.0.0（检查日志
docker logs opencode）。
5. 访问地址
- Web UI:
http://<NAS_IP>:3004
- 反向代理建议: 配合 Nginx Proxy Manager 使用，并务必开启 Access List (密码验证)，因为默认 Web 界面无鉴权。
