Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -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
33 changes: 33 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -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=<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"]
28 changes: 28 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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://<host>: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
Expand Down
24 changes: 24 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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种方式 —— 任选其一:
Expand Down Expand Up @@ -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://<host>: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
Expand Down
Loading