biliTickerBuy Docker 部署实战：从 docker run 到 docker compose 的完整配置指南

biliTickerBuy Docker 部署实战：从 docker run 到 docker compose 的完整配置指南

【免费下载链接】biliTickerBuyb站会员购购票辅助工具项目地址: https://gitcode.com/GitHub_Trending/bi/biliTickerBuy

本文围绕biliTickerBuy（B 站会员购购票辅助工具）的官方 Docker 镜像，系统讲解如何通过docker run与docker compose两种方式完成容器化部署，覆盖最小启动、数据持久化挂载、环境变量配置、镜像更新与典型故障排查。读完本文，你将能够独立在一台仅装有 Docker Engine / Docker Desktop 的服务器上，把biliTickerBuy以可持久化的 Web 服务形态长期稳定运行，并理解每个环境变量在源码中的真实作用。

一、部署前置要求与镜像来源

biliTickerBuy官方已提供构建好的容器镜像，无需从源码自行编译。部署前需要确认：

• 已安装Docker Engine或Docker Desktop；
• 若计划使用docker compose编排，需要额外安装Docker Compose插件（新版 Docker Desktop 与多数发行版 Docker Engine 已内置）。

镜像发布在 GitHub Container Registry（GHCR），镜像名为：

ghcr.io/mikumifa/bilitickerbuy

默认拉取标签为latest；也可以使用固定版本标签（例如v2.15.8）。镜像中已内置了应用运行所需的完整 Python 运行时、依赖与中文字体，构建细节见仓库根目录的 Dockerfile：

• 基础镜像为python:3.12-slim；
• 预装fontconfig与fonts-wqy-microhei/fonts-wqy-zenhei中文字体，确保 Web 界面与抢票日志中的中文正常渲染；
• 设置时区TZ=Asia/Shanghai，并默认写入BTB_SERVER_NAME=0.0.0.0、GRADIO_SERVER_PORT=7860、GRADIO_NUM_PORTS=100、BTB_DOCKER=1等环境变量；
• 暴露7860端口，容器启动命令为python main.py，即直接进入 Web UI 模式。

二、方式一：使用 docker run 部署

2.1 最小启动

不关心数据持久化时，一条命令即可拉起服务：

docker run -d \ --name bilitickerbuy \ -p 7860:7860 \ -e BTB_SERVER_NAME=0.0.0.0 \ -e GRADIO_SERVER_PORT=7860 \ ghcr.io/mikumifa/bilitickerbuy:latest

启动后通过浏览器访问：

http://服务器IP:7860

其中-e BTB_SERVER_NAME=0.0.0.0让服务监听容器内所有网卡（配合端口映射对外暴露），GRADIO_SERVER_PORT=7860与-p 7860:7860保持一致。这两个变量在 Dockerfile 中已作为默认值写入，此处显式声明主要是为了可读性。

注意：BTB_SERVER_NAME在非 Docker 环境下的默认值是127.0.0.1（见 app_cmd/cli_args.py），仅监听本机；容器内由 Dockerfile 改写为0.0.0.0，所以必须配合端口映射或防火墙放行才能从宿主机外部访问。

2.2 带持久化挂载启动（推荐）

容器是临时性的：docker rm之后，容器内写入的配置、登录 Cookies、日志都会一并消失。长期使用建议把四类数据全部挂载到宿主机：

docker run -d \ --name bilitickerbuy \ -p 7860:7860 \ -e BTB_SERVER_NAME=0.0.0.0 \ -e GRADIO_SERVER_PORT=7860 \ -e GRADIO_NUM_PORTS=100 \ -e BTB_CONFIG_PATH=/app/data/config.json \ -e BTB_COOKIES_PATH=/app/data/cookies.json \ -e BTB_LOG_DIR=/app/data/btb_logs \ -v $(pwd)/data:/app/data \ ghcr.io/mikumifa/bilitickerbuy:latest

其中-v $(pwd)/data:/app/data把宿主机当前目录下的data文件夹映射到容器内/app/data（/app是镜像设定的工作目录），配置、Cookies、日志都写到这个卷里，删容器不丢数据。

Windows PowerShell 下写法略有差异（续行符为反引号，路径变量用${PWD}）：

docker run -d ` --name bilitickerbuy ` -p 7860:7860 ` -e BTB_SERVER_NAME=0.0.0.0 ` -e GRADIO_SERVER_PORT=7860 ` -e GRADIO_NUM_PORTS=100 ` -e BTB_CONFIG_PATH=/app/data/config.json ` -e BTB_COOKIES_PATH=/app/data/cookies.json ` -e BTB_LOG_DIR=/app/data/btb_logs ` -v ${PWD}/data:/app/data ` ghcr.io/mikumifa/bilitickerbuy:latest

2.3 查看日志与停止容器

# 实时跟踪日志 docker logs -f bilitickerbuy # 停止并删除容器 docker rm -f bilitickerbuy

日志会写入容器标准输出（docker logs可看），同时应用也会按BTB_LOG_DIR落盘日志文件。

三、方式二：使用 docker compose 部署

对于长期运行、需要「一键启停 + 自动重启 + 集中管理环境变量」的场景，官方推荐docker compose。一份最小可用的compose.yaml如下：

services: bilitickerbuy: image: ghcr.io/mikumifa/bilitickerbuy:latest container_name: bilitickerbuy restart: unless-stopped ports: - "7860:7860" environment: BTB_SERVER_NAME: 0.0.0.0 GRADIO_SERVER_PORT: 7860 GRADIO_NUM_PORTS: 100 BTB_CONFIG_PATH: /app/data/config.json BTB_COOKIES_PATH: /app/data/cookies.json BTB_LOG_DIR: /app/data/btb_logs volumes: - ./data:/app/data

要点说明：

• restart: unless-stopped：容器异常退出或宿主机重启后自动拉起，是长期运行的关键；
• volumes: ./data:/app/data：与 2.2 节中的挂载一一对应，实现配置/登录态/日志持久化；
• 环境变量集中写在environment下，后续想调整通知渠道或抢票参数，只需改这一个文件。

启动、查日志、停止：

docker compose up -d # 后台启动 docker compose logs -f # 跟踪日志 docker compose down # 停止并移除容器（数据卷 ./data 保留）

仓库根目录还自带了一份示例 docker-compose.yml，它与上面略有不同：采用的是build: .（从本地源码构建）方式，并额外演示了BTB_ROOT_PATH的用法——当通过远端 IP、域名或反向代理访问时，可把它设置为浏览器实际访问的外部地址（如http://your-server-ip:7860或https://your-domain.example），并在注释中给出通过环境变量持久化代理池与通知配置的示例（BTB_HTTPS_PROXYS、BTB_PUSHPLUSTOKEN、BTB_BARKTOKEN、BTB_NTFY_URL）。日常直接使用官方镜像时，照抄上文基于image:的版本即可。

四、常用环境变量详解（附源码级实现依据）

官方镜像已在 Dockerfile 中写入了部分默认值，其余变量可按需在docker run -e或compose.yaml的environment中覆盖。下表汇总了部署中最常用的变量：

环境变量	说明	默认值
BTB_SERVER_NAME	Web 服务监听地址	0.0.0.0
GRADIO_SERVER_PORT	Web 服务端口	7860
GRADIO_NUM_PORTS	Gradio 可用端口池大小	100
BTB_CONFIG_PATH	配置文件路径	默认/app/config.json，Docker 推荐/app/data/config.json
BTB_COOKIES_PATH	Cookies 文件路径	默认/app/cookies.json，Docker 推荐/app/data/cookies.json
BTB_LOG_DIR	日志目录	默认/app/btb_logs，Docker 推荐/app/data/btb_logs
BTB_SHARE	是否启用 Gradio 公网分享	false
BTB_PUSHPLUSTOKEN	PushPlus 通知 token	空
BTB_BARKTOKEN	Bark 通知 token	空
BTB_NTFY_URL	ntfy 推送地址	空
BTB_NTP_SERVERS	NTP 服务器列表	空，为空时默认依次使用ntp.aliyun.com,ntp.tencent.com,cn.ntp.org.cn,time.cloudflare.com

4.1 Web 服务相关：监听、端口、公网分享与反向代理

• BTB_SERVER_NAME/GRADIO_SERVER_PORT：控制 Gradio 服务的监听地址与端口。UI 启动参数在 app_cmd/cli_args.py 中定义，其中port会依次读取BTB_PORT与GRADIO_SERVER_PORT。最终传给demo.launch(...)的调用位于 app_cmd/ticker.py。
• GRADIO_NUM_PORTS：Gradio 多进程/多端口池大小，通常无需修改。
• BTB_SHARE：是否开启 Gradio 公网分享（生成临时公网链接）。这里有一个容易忽略的源码细节：在 app_cmd/ticker.py 中，程序会通过检测/.dockerenv文件或BTB_DOCKER == "1"判断是否运行在容器内，而demo.launch的share参数取值为args.share or is_docker——也就是说在 Docker 环境下公网分享默认是开启的，即使不显式设置BTB_SHARE。若不需要公网分享，可显式将其关闭。
• BTB_ROOT_PATH：设置 Web UI 的外部访问根路径/地址，用于「远程 IP、域名、反向代理」访问场景，与demo.launch(root_path=...)直接对应（app_cmd/ticker.py）。

4.2 数据持久化相关：配置、Cookies、日志

这三个路径变量决定容器内的数据落点，是「删容器不丢数据」的关键。其解析逻辑集中在 util/init.py：

• BTB_LOG_DIR：日志目录，启动时会自动makedirs并交给 loguru 写日志（util/init.py）；
• BTB_CONFIG_PATH：即ConfigDB（KVDatabase）的持久化文件路径（util/init.py），前端配置与运行参数都存在这个 JSON 文件里；
• BTB_COOKIES_PATH：全局 Cookies 文件路径（util/init.py），保存登录态。

它们同时会被加入 Gradio 的allowed_paths（app_cmd/ticker.py），这也是下一节「InvalidPathError」报错的根源与解法所在。此外，容器内默认BTB_DOCKER=1，inbrowser参数会被置为False（app_cmd/ticker.py），避免容器中试图拉起浏览器。

4.3 通知渠道相关：PushPlus / Bark / ntfy

BTB_PUSHPLUSTOKEN、BTB_BARKTOKEN、BTB_NTFY_URL对应抢票成功或代理池耗尽时的三类通知渠道，实现在 app_cmd/config/NotifierConfig.py 中，分别映射到pushplusToken、barkToken、ntfy_url运行参数。在 Docker 场景下，通过环境变量注入这些值，可避免每次启动容器后在前端重新填写。

4.4 时间同步相关：BTB_NTP_SERVERS

抢票对时间精度敏感，应用启动时会进行 NTP 校时。BTB_NTP_SERVERS为空时，使用 util/TimeUtil.py 中定义的默认服务器列表：

ntp.aliyun.com, ntp.tencent.com, cn.ntp.org.cn, time.cloudflare.com

设置该变量时，util/init.py 会按逗号拆分并构造自定义TimeUtil实例；若网络环境无法访问这些公网 NTP 服务器（例如内网部署），可以改为内网 NTP 地址。

4.5 其他可注入的抢票参数（进阶）

除部署类变量外，BTB_*环境变量还可覆盖大量抢票运行参数，优先级为CLI 显式参数 > 环境变量（BTB_*） > 内置默认值（该优先级由 main.py 的merge_env与_explicit_cli_flags实现，并被 tests/test_buy_env_vars.py 的单元测试覆盖验证）。例如：

环境变量	说明	默认值
BTB_INTERVAL	默认请求间隔（毫秒）	1000
BTB_HTTPS_PROXYS	代理字符串或逗号分隔的代理池	none
BTB_PROXY_API_URL	代理供应商 API 地址（用于补充代理池）	空
BTB_CREATE_RETRY_LIMIT	每轮创建订单的最大重试次数	见 app_cmd/config/BuyConfig.py
BTB_LOG_LEVEL	日志级别预设：simple/standard/debug	standard
BTB_LOG_RETENTION_DAYS	日志文件保留天数	7

完整字段定义可查阅 app_cmd/config/BuyConfig.py 与 app_cmd/config/NotifierConfig.py。这些变量在「前端暂未配置但希望容器启动即生效」的场景下非常实用。

五、更新镜像

5.1 docker run 场景

更新到最新镜像并重建容器：

docker pull ghcr.io/mikumifa/bilitickerbuy:latest docker rm -f bilitickerbuy docker run -d \ --name bilitickerbuy \ -p 7860:7860 \ -e BTB_SERVER_NAME=0.0.0.0 \ -e GRADIO_SERVER_PORT=7860 \ -e GRADIO_NUM_PORTS=100 \ -e BTB_CONFIG_PATH=/app/data/config.json \ -e BTB_COOKIES_PATH=/app/data/cookies.json \ -e BTB_LOG_DIR=/app/data/btb_logs \ -v $(pwd)/data:/app/data \ ghcr.io/mikumifa/bilitickerbuy:latest

如果希望锁定版本，把latest替换为目标版本标签即可，例如：

ghcr.io/mikumifa/bilitickerbuy:v2.15.8

5.2 docker compose 场景

修改compose.yaml中的镜像标签后：

docker compose pull docker compose up -d

docker compose up -d会基于新拉取的镜像重建容器；由于配置、Cookies、日志都挂载在./data卷中，升级过程不丢失登录状态与配置。可用版本标签以 GitHub Packages 页面公布为准。

六、常见问题排查

6.1 无法访问页面

按以下顺序排查：

1. 容器是否正常运行：docker ps；
2. 日志中是否有报错：docker logs -f bilitickerbuy；
3. 宿主机防火墙是否放行7860；
4. 云服务器安全组是否放行7860。

6.2 配置和登录状态丢失

未挂载config.json、cookies.json、btb_logs、btb_runs时，删除容器后这些内容会一起消失。长期部署请使用docker compose，或至少在docker run中加上数据卷挂载（见 2.2 节）。注意：除了文档中明确提到的btb_logs，运行任务产生的btb_runs目录同样建议持久化，否则任务运行记录也会随容器销毁。

6.3 报错IsADirectoryError: /app/config.json

这通常意味着把一个目录挂载到了本应是文件的配置路径上。修复步骤：

1. 删除错误创建的目录；
2. 重新创建config.json和cookies.json空文件（或在首次启动后由程序自动生成）；
3. 改用整目录挂载./data:/app/data；
4. 把BTB_CONFIG_PATH设置为/app/data/config.json；
5. 把BTB_COOKIES_PATH设置为/app/data/cookies.json。

6.4 报错gradio.exceptions.InvalidPathError

这通常说明你把持久化文件放到了/data这类不在 Gradio 默认允许范围内的目录。最直接的修复是把数据目录挂到/app/data——因为/app就是应用当前工作目录，且应用会主动把配置、Cookies、日志目录加入 Gradio 的allowed_paths（app_cmd/ticker.py）：

-e BTB_CONFIG_PATH=/app/data/config.json \ -e BTB_COOKIES_PATH=/app/data/cookies.json \ -e BTB_LOG_DIR=/app/data/btb_logs \ -v $(pwd)/data:/app/data \

6.5 想使用其他镜像标签

前往 GitHub Packages 页面（ghcr.io/mikumifa/bilitickerbuy的对应页面）查看当前可用标签，然后在docker run或compose.yaml中替换即可。

七、总结

biliTickerBuy的 Docker 部署本质上只需把握三个要点：端口与监听（BTB_SERVER_NAME/GRADIO_SERVER_PORT）、数据持久化（BTB_CONFIG_PATH/BTB_COOKIES_PATH/BTB_LOG_DIR+ 整目录挂载/app/data）、按需注入运行参数（通知渠道、代理、NTP 等BTB_*变量）。docker compose配合restart: unless-stopped与数据卷，是长期稳定运行的推荐方案；而docker run则适合快速验证与临时测试。镜像本身已内置中文字体、时区与完整运行环境，开箱即用。

如需进一步了解本地源码构建、升级机制或更细粒度的配置项，可继续阅读仓库内的 docs/installation.md、Dockerfile 与 app_cmd/config/BuyConfig.py。

【免费下载链接】biliTickerBuyb站会员购购票辅助工具项目地址: https://gitcode.com/GitHub_Trending/bi/biliTickerBuy