[ranxianglei]

Closes #3389

Adds first-class Docker support: a Dockerfile at the repository root plus docs, so docker build && docker run yields a working proxy.

What changed

• Dockerfile (repo root) — node:24-slim base; installs the published npm package at build time (ARG BILI_VERSION=latest, pin with --build-arg BILI_VERSION=0.1.197); CMD ["bili","--host","0.0.0.0","--port","8787"]; EXPOSE 8787; declares the four XDG dirs from src/paths.ts as VOLUMEs; HEALTHCHECK probes /__bili/health with node's builtin fetch (no curl in slim).
• .dockerignore — the image COPYs nothing from the context (npm install at build time), so this shrinks the build context to just the Dockerfile itself.
• README.md / README.zh-CN.md — new "Running in Docker / 在 Docker 中运行" subsection under "Running the proxy" (build/run example, volume mapping, update model, security + healthcheck notes) and a one-line pointer in the Install section. zh/en kept in sync.

Design decisions (all reuse existing mechanisms — zero new config surface)

• Base = node:24-slim. The SQLite engine ladder prefers builtin node:sqlite (Node ≥ 22.5), so the container never downloads a native addon. Node 20 bases are documented as unsupported: the self-downloaded better-sqlite3@13 requires Node ≥ 22 and crashes under 20 (Node 20 Docker startup segfaults after SQLite self-bootstrap #3341 — where a real user hit exactly this while hand-rolling a Docker deployment).
• ENV ACP_AUTO_UPDATE=0 — behavior default of the new artifact. Per the Install-Lane & Update-Ownership Contract, the sanctioned update channel for a containerized copy is rebuilding/pulling a newer image. An in-place self-update mutates the container filesystem and is silently reverted to the image version on the next recreate = silent version drift. Users who want the old behavior opt back in with -e ACP_AUTO_UPDATE=1. Advisory checks stay on (independent fail-open mechanism, the product's designed "autoUpdate off" posture).
• The --host 0.0.0.0 no-auth caveat is carried into the docs: expose 8787 only on trusted networks.

Verification (targeted, local — no docker available in this environment)

Verified the image's runtime contract natively against the published artifact v0.1.197: fresh isolated XDG env + ACP_AUTO_UPDATE=0 + exact CMD → healthy within 1s (GET /__bili/health → {"ok":true,...}), storage engine resolved to node:sqlite/builtin (no addon download), all state written under the four declared dirs, clean SIGTERM flush; the exact HEALTHCHECK expression executed → exit 0. Full-suite verdict comes from CI on this head.

Out of scope (follow-up candidate)

CI-built/pushed registry images (ghcr.io vs elsewhere needs an owner decision) — separate issue when wanted.

[github-actions]

📦 Built Package Artifact

Branch: 2026-10-16_dockerfile (456d6f8)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3996-pr.3392.773f63d

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr3392.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重：不重复。 检索 open+closed issues/PR（docker/container 关键词）：无既有「官方 Dockerfile / 容器化部署」条目。相关但不同：#3341（用户手搓 Docker 部署遇 Node 20 崩溃——需求真实性证据 + 基础镜像下限依据）；#697（CI 内 docker 仅跑 codex e2e，与产品部署无关）。本 PR 即 #3389 的交付物。

开始按 PR Review 规范审：①原 issue 方向 → ②回归审查 → ③代码 → ④测试有效性 → ⑤/⑤b diff 与代码整洁，结论按八问给出。PR head e3e38d4ea（base f76668963），master 已前进到 83197e913，会先 rebase 核对再下结论。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

PR #3392 审核结论(独立重审,非复读 issue 侧分析)

做了什么:逐行重读全部 diff(+89/-0,仅 4 个文件:Dockerfile、.dockerignore、README.md、README.zh-CN.md,零代码改动);把 PR 里每一条事实性声明对照源码逐一验证;rebase 到当前 master(83197e913,无冲突,force-with-lease 推回 PR 分支,新 head 456d6f8ee);远端 CI 全窗跑完。

逐项验证结果(全部属实):

• /__bili/health:src/server/admin.ts:198 — bootReady 前返回 503 {ok:false,reason:"starting"}(Windows: concurrent lane proxies can double-bind the same zone port (SO_REUSEADDR semantics) — instance pointer diverges from the socket owner #2941 门禁),之后 200 {ok:true,…}。HEALTHCHECK 用 r.ok?0:1,503 判为不健康、start-period=15s 覆盖启动窗口,语义正确。
• ACP_AUTO_UPDATE=0:src/config.ts:1364 — (env.ACP_AUTO_UPDATE ?? …) !== "0" → 镜像内自更新确实关闭。
• 四个 VOLUME 路径与 src/paths.ts 的 XDG 目录一一对应(config / local/share / cache / local/state,billion-context 后缀),容器以 root 运行 homedir=/root,路径精确匹配。
• SQLite 引擎阶梯:src/storage/driver.ts(builtin node:sqlite → host better-sqlite3 → self-downloaded)+ src/storage/engine-bootstrap.ts —— Node 24 恒有 builtin,容器内确实不会下载 native addon;Node 20 禁用说明对应 Node 20 Docker startup segfaults after SQLite self-bootstrap #3341 的真实事故,准确。
• README 交叉引用有效:Option 3 = /bili/ 前缀方式,--host/--port flag 存在,无认证注意事项与「Remote agents」节一致;en/CJK 锚点 slug 均正确;zh/en 内容同步无漂移。
• .dockerignore(* + !Dockerfile)与「构建期从 npm 装、不 COPY 任何源码」的设计自洽。
• 文档示例钉的 BILI_VERSION=0.1.197 = 当前 npm latest,示例有效。

CI(head 456d6f8ee):30 项检查全绿——19 success + 11 gated-skip(e2e 门控 lane,默认跳过属正常)+ 0 failed。

结构化八问

1. 是什么问题:需求类——给 bili 提供一等公民的容器部署方式,docker build && docker run 即得可用代理(Add Dockerfile for installing and running in Docker | 增加dockerfile，支持在docker中安装运行 #3389)。
2. 什么原因导致的:不涉及(非缺陷)。
3. 影响范围与严重程度:纯新增产物,现有安装零影响。对容器用户:镜像内默认行为与裸机不同(自更新关、监听 0.0.0.0),均已在 PR 描述和 README 中显式披露并给出回退开关。
4. 怎么修复的:复用既有机制实现容器化——构建期装已发布 npm 包(镜像内零编译)、node:24-slim 吃 builtin sqlite、按 Install-Lane & Update-Ownership Contract 把镜像重建/pull 定为唯一合法升级通道(故 ACP_AUTO_UPDATE=0 为镜像默认)、四个 XDG 目录声明 VOLUME、node 内置 fetch 做健康检查。
5. 是否有回归问题:无。diff 不触碰任何源码,既有二进制行为/线上协议/持久化格式全部不变。高危域点名核查:自动更新路径(只经既有 env 在镜像层关闭,未改 src/update.ts)、dsh/lockfile/systemd 模板、网络/代理路径——均未触碰。
6. 是否破坏缓存:不涉及。
7. 是否改了设计方向:没有。零新增配置面(已核实:复用的全是既有 env/flag/端点)。
8. 是否引入了新的配置:无新 env/config/CLI flag。镜像内的 ACP_AUTO_UPDATE=0 是新产物的默认值(旧值→新值:裸机默认开 → 容器镜像默认关,原因:原地自更新会在容器重建时被静默回退 = 静默版本漂移;opt-back 开关 -e ACP_AUTO_UPDATE=1 已写进文档)。

两条非阻塞观察(记录在案,不拦):① 镜像无 USER 指令,以 root 运行——符合 node:slim 惯例且四个 VOLUME 路径按 /root 布局,做 non-root 需要整套 chown/路径改造,当前取舍合理;② advisory(critical-defect 强制更新)机制独立于 autoUpdate,即使镜像内关了自更新,critical advisory 仍可能改写容器文件系统(重建后回退)——这是产品设计的 fail-open critical 通道,与文档所述「autoUpdate off posture」一致,接受现状,若未来出现容器场景下的真实案例再议。

判定:可合。 rebase 后 CI 全绿,diff 干净(每一行都服务于本 PR 目的),zh/en 同步,声明全部经源码验证。合并动作留给人工:#3392

[github-actions]

📦 Merged Build Published

This merge to master was published as 0.0.664-master.2b7829f (rolling master tag).

npm install -g billion-context@0.0.664-master.2b7829f  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.