Databag 0.1.18 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 Databag 服务端 0.1.18，含持久化、环境变量、反向代理与 TLS 说明。以下命令与回显均来自 2026-10-25 的真实部署实测（Docker 29.x + Compose v2，镜像 balzack/databag:0.1.18）。

一、环境信息

操作系统：Ubuntu 22.04 LTS（amd64；镜像同时提供 arm64）
组件版本：Databag 服务端 0.1.18（镜像推送于 2025-10-15，为 Docker Hub 当前最新服务端标签）
镜像：balzack/databag:0.1.18（约 1.07GB，内含 Go 服务端 + React Web 客户端 + ImageMagick/FFmpeg/sqlite）
容器内端口：7000（HTTP）
数据目录：容器内 /var/lib/databag（SQLite 库 + 账号附件）

二、镜像选型说明

Docker Hub 上 balzack/databag 的标签情况（实查 2026-10-25）：

标签	推送时间	说明
`0.1.18`	2025-10-15	当前最新，本文固定使用
`latest`	2024-09-16	停更在旧版（约等于 0.1.17），勿用
`0.1.17` 及更早	2024 年	历史版本
`test`	2025-09-08	测试构建，勿用于生产

⚠️ 注意：latest 标签停在 2024-09，并不指向最新构建；必须显式锁定 0.1.18。另外 GitHub Releases 的 v1.1.x 是客户端 App 版本线，与服务端镜像版本号无关，勿混淆。

三、前置条件

已安装 Docker Engine 与 Compose v2 插件（docker compose version 可用）
本机 7000 端口空闲（或改用其他端口）
正式对外使用需准备 DNS 域名 + TLS 证书（客户端强制要求；本机体验可跳过）

四、部署步骤

4.1 编写 docker-compose.yml

name: databag-0.1.18-stack

services:
  databag:
    image: balzack/databag:0.1.18
    container_name: databag-0.1.18-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:7000:7000"
    environment:
      - ADMIN=q1w2e3r4
    volumes:
      - databag-data:/var/lib/databag

volumes:
  databag-data:

要点说明：

ADMIN=q1w2e3r4：管理员初始口令（演示口令，生产请替换）。镜像入口脚本会把它写入内置 SQLite 的 configs 表；每次启动都会用该值重置管理员口令。
端口绑定 127.0.0.1:7000:7000：只允许本机访问，公网暴露交给反向代理（推荐）；本机直跑可改为 7000:7000。
databag-data 卷挂到 /var/lib/databag：SQLite 库与全部用户附件都在里面。

4.2 启动

docker compose up -d
docker compose ps

实测回显：

 Container databag-0.1.18-server Started

NAME                    IMAGE                    COMMAND                  SERVICE   CREATED         STATUS         PORTS
databag-0.1.18-server   balzack/databag:0.1.18   "/bin/sh -c /app/dat…"   databag   4 seconds ago   Up 4 seconds   127.0.0.1:7000->7000/tcp

启动日志确认参数与端口：

docker logs databag-0.1.18-server

2026/10/25 04:52:20 using args: -s /var/lib/databag -w /app/databag/net/web/build -p 7000 -t /opt/databag/transform

4.3 验证部署

# Web 客户端首页
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:7000/

HTTP 200

# 管理员登录，换取会话令牌
curl -s -X PUT "http://127.0.0.1:7000/admin/access?token=q1w2e3r4"

"8db81ec2b687add9b16cf72415dbf604"

# 用会话令牌读取节点配置
curl -s "http://127.0.0.1:7000/admin/config?token=8db81ec2b687add9b16cf72415dbf604"

{"domain":"","enableImage":true,"enableAudio":true,"enableVideo":true,"enableBinary":true,"enableIce":false,"iceService":"","iceUrl":"","iceUsername":"","icePassword":"","keyType":"RSA2048","accountStorage":0,"transformSupported":true,"allowUnsealed":true,"pushSupported":true}

浏览器访问 http://<主机IP>:7000，右上角齿轮 → 输入 q1w2e3r4 进入管理台 → 设置节点域名 → 点「添加用户」生成账号创建链接，把链接发给使用者开户。

五、数据持久化说明

唯一需要持久化的路径是 /var/lib/databag：

$ docker exec databag-0.1.18-server ls /var/lib/databag/
databag.db

databag.db：SQLite 库，账号、配置、消息元数据全在其中
账号附件：按账号公钥指纹建子目录存放（有账号产生内容后出现）
备份 = 停服后复制整个 /var/lib/databag（或直接备份卷）；恢复 = 还原后启动

换用绑定挂载（数据直接落宿主目录，便于备份脚本处理）：

    volumes:
      - /srv/databag:/var/lib/databag

六、环境变量表

镜像入口脚本（entrypoint.sh）消费的环境变量，实测确认行为：

变量	默认值	说明
`ADMIN`	`password`（Dockerfile 内置）	管理员口令。每次启动都会重置为该值，务必显式设置
`DATABAG_PORT`	`7000`	容器内监听端口，改了需同步调整端口映射
`DEV`	`0`	`1` 为开发模式（nohup 后台 + tail 日志），生产勿动

⚠️ 注意：ADMIN 在每次容器启动时都会覆盖数据库中的管理员口令。运行期通过管理台改口令后，若重启容器会被环境变量改回去——改口令应同步更新 compose 文件，或启动后移除该变量。

七、配置参数说明

业务配置（域名、存储配额、媒体开关、TURN 中继、开放注册、MFA 等）不落文件，全部存于 SQLite configs 表，运行时通过管理台或 PUT /admin/config 接口修改。逐项含义、默认值与实测修改示例见《Databag 0.1.18 配置参数详解》。

最常用的起步配置（设置节点域名，联邦通信的前提）：

SESSION=$(curl -s -X PUT "http://127.0.0.1:7000/admin/access?token=q1w2e3r4" | tr -d '"')
curl -s -X PUT "http://127.0.0.1:7000/admin/config?token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"databag.example.com","accountStorage":1073741824,"allowUnsealed":true,"enableImage":true,"enableAudio":true,"enableVideo":true,"enableBinary":true,"keyType":"RSA2048","enableIce":false,"iceService":"","iceUrl":"","iceUsername":"","icePassword":""}'

⚠️ 实测注意：PUT /admin/config 是全量覆盖语义——未提交的字段会被重置成零值（false/0/空串），修改时务必带上全部字段。

八、配置文件挂载

Databag 没有传统意义的配置文件（配置在 SQLite 里），唯一可能从宿主挂入的是 TLS 证书（不用反向代理、由服务端直挂 TLS 时）：

    volumes:
      - databag-data:/var/lib/databag
      - ./pki/cert.pem:/pki/cert.pem:ro
      - ./pki/key.pem:/pki/key.pem:ro

但镜像入口脚本不支持自定义启动旗标（固定 -p/-s/-w/-t），要直挂证书需覆盖入口命令：

    entrypoint: ["/app/databag/net/server/databag","-p","7000","-s","/var/lib/databag","-w","/app/databag/net/web/build","-t","/opt/databag/transform","-c","/pki/cert.pem","-k","/pki/key.pem"]

💡 说明：覆盖 entrypoint 会跳过入口脚本里的建表与 ADMIN 预置，首次启动前需手工初始化 configs 表（SQL 见《Ubuntu 22.04 安装 Databag 0.1.18 指南》方案 A 第 4.6 节）。多数场景更推荐用 Nginx/NPM/Caddy 反向代理终结 TLS。

九、等价 docker run

与上方 compose 完全等价的单命令：

docker run -d \
  --name databag-0.1.18-server \
  --restart unless-stopped \
  -p 127.0.0.1:7000:7000 \
  -e ADMIN=q1w2e3r4 \
  -v databag-data:/var/lib/databag \
  balzack/databag:0.1.18

十、常用运维命令

docker compose ps                 # 查看运行状态
docker compose logs -f databag    # 跟随日志
docker compose restart databag    # 重启
docker compose down               # 停止并删除容器（数据卷保留）
docker compose down -v            # 连数据卷一起删（清空全部数据，危险）
docker compose pull && docker compose up -d   # 拉新镜像并滚动更新

十一、常见问题

Q1：管理台登录提示口令错误？ ADMIN 每次启动都会重置库内口令。用 compose 里的 ADMIN 值登录；改过库内口令的，重启后会被覆盖回 ADMIN。

Q2：移动端 App 连不上 http://IP:7000？ App 强制要求 HTTPS + DNS 域名。给节点配域名和证书（反向代理或直挂），然后在管理台把 Federated Host（域名）设置为该域名。

Q3：音视频通话不通？ 通话走 WebRTC，需要 STUN/TURN 中继。管理台开启 WebRTC 并填入中继地址/账号；自建可用 coturn，或用 Cloudflare TURN 服务。相关参数见《Databag 0.1.18 配置参数详解》。

Q4：升级版本怎么做？ 改 compose 里镜像标签 → docker compose pull && docker compose up -d。数据全在卷里，跨版本启动无需额外迁移（0.1.x 系列内实测平滑）。

十二、参考链接

Docker Hub 镜像标签：https://hub.docker.com/r/balzack/databag/tags
GitHub 仓库：https://github.com/balzack/databag
官方 compose 示例（仓库根 docker-compose.yml）：https://github.com/balzack/databag/blob/main/docker-compose.yml