快速开始

本指南帮助你用 Docker 装好 Bonita，并完成第一次登录。

安装

推荐用 Docker。镜像：suwmlee/bonita:latest，Web 端口 12346。

基本运行

docker pull suwmlee/bonita:latest
docker run -d -p 12346:12346 suwmlee/bonita:latest

完整示例

把媒体目录和数据目录挂进去，并指定初始管理员（只在第一次创建数据库时生效）：

docker run -d \
    --name bonita \
    -p 12346:12346 \
    -e PUID=0 \
    -e PGID=0 \
    -e TZ=Asia/Shanghai \
    -e FIRST_SUPERUSER_EMAIL="[email protected]" \
    -e FIRST_SUPERUSER_PASSWORD="changepwd" \
    -e MAX_CONCURRENCY=5 \
    -v <path/to/media>:/media \
    -v <path/to/data>:/app/backend/data \
    suwmlee/bonita:latest

可选：用外部 Redis 做 Celery broker：

docker run -d \
    --name bonita \
    -p 12346:12346 \
    -e PUID=0 \
    -e PGID=0 \
    -e CELERY_BROKER_URL="redis://host.docker.internal:6379/0" \
    -e CELERY_RESULT_BACKEND="redis://host.docker.internal:6379/0" \
    -e MAX_CONCURRENCY=5 \
    -v <path/to/media>:/media \
    -v <path/to/data>:/app/backend/data \
    suwmlee/bonita:latest

docker-compose（推荐）

创建 docker-compose.yml：

services:
  bonita:
    container_name: bonita
    image: suwmlee/bonita:latest
    ports:
      - "12346:12346"
    environment:
      - PUID=0
      - PGID=0
      - TZ=Asia/Shanghai
      - [email protected]
      - FIRST_SUPERUSER_PASSWORD=changepwd
      - MAX_CONCURRENCY=5
    volumes:
      - <path/to/data>:/app/backend/data
      - <path/to/media>:/media
    restart: unless-stopped

docker compose up -d

媒体目录建议和 Emby 看到的是同一套文件（硬链接或同一挂载）。路径对得上，观看记录和合集才更容易匹配。

环境变量

变量	默认值	说明
PUID / PGID	0	容器内进程用户/组，需能读写挂载的媒体和数据目录
TZ	Asia/Shanghai	时区
FIRST_SUPERUSER	admin	初始管理员用户名（仅首次建库）
FIRST_SUPERUSER_EMAIL	[email protected]	初始管理员邮箱，登录用这个（仅首次建库）
FIRST_SUPERUSER_PASSWORD	changepwd	初始管理员密码（仅首次建库）
MAX_CONCURRENCY	镜像内 1	Celery worker 并发。为 1 时子任务同步执行；大于 1 时并行投递
MAX_CONCURRENT_TASKS	5	同时执行的转移任务数上限
CELERY_BROKER_URL	SQLite	外部 broker，例如 Redis
CELERY_RESULT_BACKEND	SQLite	外部结果存储
MONITOR_USE_POLLING	false	SMB/CIFS 等网络盘建议设为 true
MONITOR_POLLING_INTERVAL	30	轮询间隔（秒）
WATCH_HISTORY_SYNC_INTERVAL	900	定时全量同步观看记录的间隔（秒）
BONITA_CONFIG	./data/config.yaml	YAML 配置文件路径

也可以把配置写在 config.yaml，默认放在 /app/backend/data/。YAML 优先于环境变量。

PROJECT_NAME: Bonita

CELERY_BROKER_URL: redis://192.168.1.10:6379/0
CELERY_RESULT_BACKEND: redis://192.168.1.10:6379/0

MAX_CONCURRENT_TASKS: 5
WATCH_HISTORY_SYNC_INTERVAL: 900

MONITOR_USE_POLLING: true
MONITOR_POLLING_INTERVAL: 30

打开界面

容器起来后，浏览器访问 http://<设备IP>:12346，用上面的邮箱和密码登录。

建议先做这几步：

1. 服务设置 — 需要刮削走代理时先配代理；要同步 Emby 就填地址、用户名、API Key
2. 刮削配置 — 新建一条并保存，会生成默认规则
3. 任务配置 — 指定源目录、输出目录，按需关联刮削和自动监视
4. 需要实时同步观看状态时，把 Webhook 填到 Emby（见 媒体服务）

服务管理

镜像用 s6-overlay 管进程。当前长期服务主要是 nginx 和 bonita（bonita 里同时跑 FastAPI 和 Celery worker + beat）。

# 服务状态
docker exec bonita /command/s6-rc -a list

# 重启 API + Celery
docker exec bonita /command/s6-rc -d change bonita
docker exec bonita /command/s6-rc -u change bonita

# 容器日志
docker logs bonita

# 进程是否在跑
docker exec bonita /command/s6-svstat /run/service/bonita

常见问题

重新部署后提示账号密码错误

FIRST_SUPERUSER_* 只在第一次创建数据库时写入。之后只能在 Web 里改密码。要重置管理员，需要删掉数据目录里的 db.sqlite3 再部署，其他配置也会一起丢掉。

服务起不来

1. docker logs bonita 看 uvicorn / celery 报错
2. docker exec bonita /command/s6-rc -a list 看服务状态
3. 确认 PUID/PGID 对数据目录和媒体目录有读写权限

网络盘监视不到新文件

把 MONITOR_USE_POLLING 设为 true。

下一步

• 基本配置 — 任务、刮削、记录
• 媒体服务 — Emby、Webhook、合集
• 主要功能
• 问题反馈：GitHub Issues