diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000..89299b82d8 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,4 @@ +# The Dockerfile installs from npm at build time and COPYs nothing from the +# context — keep the context minimal when building from the repo root. +* +!Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..aad7eb1039 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,33 @@ +# billion-context proxy in a container (#3389). +# +# Installs the published npm package at build time (the tested artifact — no +# source is compiled in the image) and runs the proxy as a long-lived service. +# +# docker build -t billion-context . +# docker run -d --name bili -p 8787:8787 \ +# -v bili-config:/root/.config/billion-context \ +# -v bili-data:/root/.local/share/billion-context \ +# -v bili-cache:/root/.cache/billion-context \ +# -v bili-state:/root/.local/state/billion-context \ +# billion-context +# +# Updates: rebuild/pull a newer image. In-container self-update is OFF by +# default (ACP_AUTO_UPDATE=0) so the running copy can never silently drift +# from its image version; opt back in with `-e ACP_AUTO_UPDATE=1`. Pin a +# release with `--build-arg BILI_VERSION=` (default: latest). + +FROM node:24-slim + +ARG BILI_VERSION=latest +RUN npm install -g --no-audit --no-fund "billion-context@${BILI_VERSION}" + +ENV ACP_AUTO_UPDATE=0 + +EXPOSE 8787 + +VOLUME ["/root/.config/billion-context", "/root/.local/share/billion-context", "/root/.cache/billion-context", "/root/.local/state/billion-context"] + +HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \ + CMD node -e "fetch('http://127.0.0.1:8787/__bili/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))" + +CMD ["bili", "--host", "0.0.0.0", "--port", "8787"] diff --git a/README.md b/README.md index d0aef5889b..b6b3cb61cf 100644 --- a/README.md +++ b/README.md @@ -151,6 +151,9 @@ This installs the `bili` command (`bili-proxy` is kept as an alias). Hitting (pass the flag again on any future npm reinstall of `bili`) — that is the permanent fix; avoid `sudo`. +Prefer containers? A `Dockerfile` ships at the repository root — see +[Running in Docker](#running-in-docker) below. + ## Quickstart Three ways to use it — pick one: @@ -391,6 +394,31 @@ state: `~/.local/share/billion-context/` (XDG-overridable; Windows AV exclusion ## Running the proxy +### Running in Docker + +A `Dockerfile` ships at the repository root — it installs the published npm +package at build time (the tested artifact; nothing is compiled in the image) +and runs the proxy as a service: + +```bash +docker build -t billion-context . +docker run -d --name bili -p 8787:8787 \ + -v bili-config:/root/.config/billion-context \ + -v bili-data:/root/.local/share/billion-context \ + -v bili-cache:/root/.cache/billion-context \ + -v bili-state:/root/.local/state/billion-context \ + billion-context +``` + +Then point clients' baseURL at `http://:8787/bili/…` exactly like Option 3 +above. + +- **Base:** `node:24-slim` — uses the builtin `node:sqlite` storage engine directly (no native-addon download). Don't switch to Node 20 bases: the self-downloaded SQLite engine requires Node ≥ 22 and crashes under 20 (#3341). +- **Updates:** in-container self-update is **off by default** (`ACP_AUTO_UPDATE=0`) — the sanctioned update channel for a containerized copy is rebuilding/pulling a newer image; an in-place self-update would be silently reverted to the image version on the next recreate. Opt back in with `-e ACP_AUTO_UPDATE=1`; pin a release at build time with `--build-arg BILI_VERSION=0.1.197` (default `latest`). +- **Data:** the four mounted dirs hold config, session state, update throttle/lock + cached SQLite engine, and logs respectively. Mount volumes or bind mounts so they survive container replacement; the image also declares them as `VOLUME`s so even a bare `docker run` keeps them out of the container layer. +- **Security:** the container listens on `0.0.0.0:8787` so clients outside it can connect — there is **no authentication**, so expose the port only on a trusted network (same caveat as `--host 0.0.0.0` below). The web UI and `/__bili/*` JSON endpoints work unchanged through the mapped port. +- **Healthcheck:** the image ships a `HEALTHCHECK` probing `/__bili/health` on 8787 via node's builtin fetch (no curl needed in the slim base); if you override the listen port, remember the probe stays pinned to 8787. + ### Flags ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md index 16f524a089..dbe2524f15 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -145,6 +145,8 @@ npm install -g billion-context --prefix=~/.local 这会安装 `bili` 命令(`bili-proxy` 保留为别名)。旧装的是 root 属主的 prefix、现在报 `EACCES`?用 `--prefix=~/.local` 重装即可根治(以后用 npm 重装 `bili` 时记得同样带上该参数)——不要用 `sudo`。 +想用容器?仓库根目录自带 `Dockerfile`——见下文[在 Docker 中运行](#在-docker-中运行)。 + ## 快速上手 3种方式 —— 任选其一: @@ -280,6 +282,28 @@ curl -s http://localhost:8787/__bili/stats ## 运行代理 +### 在 Docker 中运行 + +仓库根目录自带 `Dockerfile`——构建期从 npm 装已发布的包(被测试过的产物;镜像里不编译任何东西),把代理作为服务跑起来: + +```bash +docker build -t billion-context . +docker run -d --name bili -p 8787:8787 \ + -v bili-config:/root/.config/billion-context \ + -v bili-data:/root/.local/share/billion-context \ + -v bili-cache:/root/.cache/billion-context \ + -v bili-state:/root/.local/state/billion-context \ + billion-context +``` + +然后把客户端 baseURL 指到 `http://:8787/bili/…`,和上面方式 3 完全一样。 + +- **基础镜像:** `node:24-slim` —— 直接用内置 `node:sqlite` 存储引擎(不发生 native addon 下载)。不要换成 Node 20 基础镜像:自举下载的 SQLite 引擎要求 Node ≥ 22,在 20 上会崩(#3341)。 +- **更新:** 容器内自更新**默认关闭**(`ACP_AUTO_UPDATE=0`)——容器化副本的合法升级通道是重建/pull 新镜像;原地自更新会在下次重建时被静默回退到镜像版本。想开回来用 `-e ACP_AUTO_UPDATE=1`;构建期钉版本用 `--build-arg BILI_VERSION=0.1.197`(默认 `latest`)。 +- **数据:** 四个挂载目录分别存放配置、会话状态、更新节流/锁 + 缓存的 SQLite 引擎、日志。挂 volume 或 bind mount 让它们跨容器替换存活;镜像也把这四个目录声明为 `VOLUME`,裸 `docker run` 也不会把它们落进容器层。 +- **安全:** 容器监听 `0.0.0.0:8787` 以便外部客户端接入——**没有认证**,端口只应暴露给可信网络(与下面 `--host 0.0.0.0` 的注意事项相同)。Web UI 和 `/__bili/*` JSON 端点经映射端口照常可用。 +- **健康检查:** 镜像自带 `HEALTHCHECK`,用 node 内置 fetch 探 8787 上的 `/__bili/health`(slim 基础无需 curl);若覆盖监听端口,注意探针仍钉在 8787。 + ### 命令行参数 ```bash