pi-courier 0.1.12 → 0.1.13

package/deploy/docker/Dockerfile

@@ -1,34 +1,72 @@
 # pi-courier — Matrix → pi 桥接服务
 #
-# 构建: docker build -t pi-courier .
-# 运行: docker compose up -d --build(见 docker-compose.yml)
+# 构建: docker compose build(只构建,不运行)
+# 运行: docker compose up -d(见 docker-compose.yml 与 README.md)
 #
 # 说明:
-#  - 基于 node:24(避开 Node 20 与 pi 的 undici 不兼容问题)
-#  - 全局安装 pi(peer 依赖)+ pi-courier
+#  - 基于 node:24-slim(避开 Node 20 与 pi 的 undici 不兼容问题;glibc 标准
+#    环境保证 agent 的 bash 工具与宿主行为一致)
+#  - 多阶段构建:builder 层装依赖后丢弃(npm 缓存/构建垃圾不进最终镜像),
+#    runtime 只带 node_modules + 运行时工具 → 体积约省 200-300MB
+#  - defaults/ 预置 LLM 三件套模板(entrypoint 首次启动自动拷贝到 /root/.pi/agent)
 #  - 构建期间 npm 会从 GitHub Releases 下载 E2EE 原生库(约 21MB),
-#    如果 VPS 网络受限,用 --build-arg HTTPS_PROXY/HTTP_PROXY 传代理
+#    网络受限时用 --build-arg HTTPS_PROXY/HTTP_PROXY 传代理
 
-FROM node:24-slim
+# ============================== builder ======================================
+FROM node:24-slim AS builder
 
-# 构建期代理(可选,仅当 VPS 需要代理访问外网时)
 ARG HTTPS_PROXY=
 ARG HTTP_PROXY=
 ENV https_proxy=${HTTPS_PROXY} \
     http_proxy=${HTTP_PROXY}
 
-# 安装 pi 与 pi-courier
+# 仅需要 ca-certificates(npm install 走 https;git 由 runtime 层负责)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安装 pi 与 pi-courier(pi 先装,pi-courier 的 peer 依赖即满足);
+# 安装后清 npm 缓存(此层最终不会进入 runtime 镜像)
 RUN npm install -g @earendil-works/pi-coding-agent pi-courier \
-    && pi --version \
+    && npm cache clean --force
+
+# ============================== runtime ======================================
+FROM node:24-slim
+
+ARG HTTPS_PROXY=
+ARG HTTP_PROXY=
+ENV https_proxy=${HTTPS_PROXY} \
+    http_proxy=${HTTP_PROXY}
+
+# 系统依赖:
+#  - git:pi 的 bash 工具 / `pi install` 需要(slim 基础镜像没有)
+#  - ca-certificates:HTTPS 证书
+#  - curl:排查网络问题用(可选)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 只带 node_modules,然后在 runtime 重建 bin 符号链接
+# (docker COPY 会把符号链接解引用成普通文件,导致相对 import 解析错误,
+#  所以不能直接 COPY /usr/local/bin/pi)
+COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -s /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js /usr/local/bin/pi \
+    && ln -s /usr/local/lib/node_modules/pi-courier/dist/cli.js /usr/local/bin/pi-courier
+
+# 验证安装(失败则构建失败)
+RUN pi --version \
     && pi-courier help >/dev/null 2>&1 \
-    && echo "node $(node --version), pi and pi-courier installed OK"
+    && echo "OK: node $(node --version), pi + pi-courier installed"
 
-# 数据卷:配置 + 会话 + 加密存储(全部在容器内 ~/.pi)
-VOLUME ["/root/.pi"]
+# 默认配置模板 + 首次启动初始化脚本
+COPY defaults/ /opt/pi-courier/defaults/
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
 
-# 进程存活检查(pi-courier run 前台运行)
+# 进程存活检查:pid 1 即 entrypoint exec 的 pi-courier run 主进程(kill -0 无需额外工具)
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
-  CMD pgrep -f "dist/standalone.js" >/dev/null || exit 1
+  CMD kill -0 1 || exit 1
 
-# 前台运行(容器主进程;Ctrl+C/SIGTERM 优雅关闭)
+# entrypoint:首次启动把模板拷进 /root/.pi/agent;随后前台运行主进程
+ENTRYPOINT ["/entrypoint.sh"]
 CMD ["pi-courier", "run"]

package/deploy/docker/README.md

@@ -5,11 +5,17 @@
 ## 目录结构
 
 ```
-pi-courier/            # 本目录(deploy/docker 的上一级)
-├── Dockerfile
-├── docker-compose.yml
-├── data/              # 自动创建:容器 ~/.pi(配置/会话/加密存储)
-└── projects/          # 可选:映射宿主机项目目录
+deploy/docker/
+├── Dockerfile            # 镜像构建(装 pi + pi-courier + 默认配置模板)
+├── docker-compose.yml    # 编排(数据卷 ./data ↔ 容器 /root/.pi)
+├── entrypoint.sh         # 首次启动:自动把默认配置模板拷入数据目录
+├── defaults/             # 模板源(构建进镜像 /opt/pi-courier/defaults/)
+│   └── agent/
+│       ├── models.json   # 完整模型数据(24 模型,开箱即用)
+│       ├── auth.json     # API key 占位(唯一需要你填的文件)
+│       └── settings.json # 默认 provider + 模型
+└── data/                 # 运行时数据(自动创建;含 key/token,已 gitignore)
+    └── agent/            # 首次启动自动从模板填充
 ```
 
 ## 部署步骤
@@ -24,71 +30,85 @@ sudo apt-get install -y docker-compose-plugin
 ```
 
 ```bash
-# 获取项目文件(任选其一)
+# 获取项目文件
 git clone https://github.com/Hi-Barry/pi-courier.git && cd pi-courier/deploy/docker
-# 或手动上传 Dockerfile + docker-compose.yml
 ```
 
-### 2. 构建并启动
+### 2. 构建(只构建,不运行)
 
 ```bash
 # 如果 VPS 需要代理访问外网(GitHub 下载 21MB E2EE 库),先导出:
 # export HTTPS_PROXY=http://<host>:<port>
 # export HTTP_PROXY=http://<host>:<port>
 
-docker compose up -d --build
-docker ps                # 确认 pi-courier 容器 running
-docker logs pi-courier   # 查看启动日志
+docker compose build
 ```
 
-### 3. 首次配置(向导)
+### 3. 配置(只需填 API key)
+
+首次启动会自动把模板拷入 `./data/agent/`。先启动一次容器完成初始化,再填 key:
+
+```bash
+docker compose up -d        # 启动(entrypoint 自动初始化 ./data/agent/)
+docker exec pi-courier ls /root/.pi/agent   # 确认模板已拷入
+```
+
+然后编辑宿主 `./data/agent/auth.json`,把占位的 `sk-你的key` 换成真实 API key:
+
+```bash
+# data/agent/auth.json
+{ "opencode-go": { "type": "api_key", "key": "sk-真实key" } }
+```
+
+> 默认 provider 是 `opencode-go` / `deepseek-v4-flash`(settings.json)。用其他 provider 的话,改 settings.json 并确认 models.json 里有对应模型。
+
+### 4. Matrix 配置(向导)
 
 ```bash
-# 容器运行后,进入交互向导(和本机一样,逐步输入)
 docker exec -it pi-courier pi-courier setup
 ```
 
-向导写入容器内 `/root/.pi/pi-courier.json`(宿主 `./data/pi-courier.json`)。
+按提示输入:homeserver → token(密码登录或粘贴)→ 信任用户 → E2EE → workdir。写入容器内 `/root/.pi/pi-courier.json`(宿主 `./data/pi-courier.json`)。
 
-> 也可以不用向导:直接在宿主 `./data/` 下创建 `pi-courier.json` 和 `agent/` 目录(对应容器 `/root/.pi/`),格式见项目 README FAQ。
+```bash
+docker compose restart      # 让 Matrix 配置生效
+docker logs pi-courier      # 应看到 ✅ Matrix connected + ✅ pi RPC connected (model: deepseek-v4-flash)
+```
 
-### 4. 使用
+### 5. 使用
 
 - 给 bot 发消息 → 查看验证码: `docker logs pi-courier` → 回复验证码配对
 - 查看日志: `docker logs -f pi-courier`(或 `docker exec pi-courier pi-courier logs --level debug`)
 - 重启: `docker compose restart`
 - 停止: `docker compose down`(数据保留在 ./data)
 
-### 5. 升级
+### 6. 升级
 
 ```bash
 # 方式 A:容器内自更新(npm 全局方式)
 docker exec pi-courier pi-courier update
 
 # 方式 B:重建镜像
-git pull && docker compose build --no-cache && docker compose up -d
+git pull && docker compose build && docker compose up -d
 ```
 
-### 6. 映射宿主机项目目录(可选)
+### 7. 映射宿主机项目目录(可选)
 
 让 pi 在容器里直接操作宿主机上的代码:
 
 1. compose 里取消注释 `- ./projects:/root/Projects`
-2. 配置 `workdir` 指向容器内路径:
-
-```bash
-docker exec -it pi-courier pi-courier setup   # workdir 填 /root/Projects/<你的项目>
-# 或直接改 ./data/pi-courier.json 的 workdir 后 docker compose restart
-```
-
-宿主机代码放 `./projects/<你的项目>`,pi 的工作目录就是 `/root/Projects/<你的项目>`。
+2. 配置 `workdir` 指向容器内路径(`docker exec -it pi-courier pi-courier setup` 的 workdir 填 `/root/Projects/<你的项目>`)
+3. 宿主机代码放 `./projects/<你的项目>`
 
 ## 常见问题
 
 | 问题 | 解决 |
 |---|---|
 | 构建很慢 / 卡在下载 | 构建期网络问题,设 `export HTTPS_PROXY` 再 build |
+| 启动显示 `model: unknown` | `./data/agent/auth.json` 没填 key,或 settings.json 的模型不在 models.json |
+| 发消息没有回复 | 按顺序查:`docker logs` 看 Matrix 连接、pi RPC 连接、模型是否 unknown |
 | `M_BAD_JSON: device_id does not match` | 重登录过,删 `./data/msg-bridge-matrix-crypto` 重启 |
 | 加密房间解不开新消息 | bot 无交叉签名,改用非加密房间 |
 | 会话重启丢失 | 0.1.1+ 自动 `--continue`,确认 `./data` 卷没被删 |
 | 想用新配置 | 改 `./data/pi-courier.json` → `docker compose restart` |
+| workdir 文件丢失(容器重建后) | 未映射 projects 卷;取消注释 `- ./projects:/root/Projects` |

package/deploy/docker/data/.gitignore

@@ -0,0 +1,4 @@
+# 运行时数据目录(容器 /root/.pi 的宿主挂载点)
+# 包含用户的 API key / token,禁止提交进 git
+*
+!.gitignore

package/deploy/docker/defaults/agent/auth.json

@@ -0,0 +1 @@
+{ "opencode-go": { "type": "api_key", "key": "sk-你的key" } }