Databunker 0.8.37 Docker Compose 部署指南

目标：在一台 Ubuntu 26.04 服务器上，用官方 Docker Compose 编排把 Databunker 0.8.37 以生产形态（应用 + PostgreSQL 后端）跑起来——生成全套密钥、完成数据库初始化、通过 API 烟测，并覆盖自定义配置挂载与 HTTPS 切换两个常见生产动作。全部命令与回显为真实执行记录。

⚠️ 本地适配说明：官方 docker-compose-pgsql.yml 原样使用 latest 应用 tag、3000 端口直暴露、无显式项目名与网段。本文为可复现实测做了三处适配并逐处标注：1) 应用 tag 由 latest 锁定为 0.8.37；2) 显式 name: databunker-0837-stack 项目名与固定网段 10.89.58.0/24（本机多栈并存的环境卫生要求）；3) 宿主端口 3000→8134（本机 3000 已被占用）。读者单栈部署可直接沿用官方原值。

一、环境信息

项目	值
宿主操作系统	Ubuntu 26.04.1 LTS（内核 7.0.0-38-generic，x86_64）
Docker 引擎	29.9.2（build a28e528）
Docker Compose	v5.6.1
Databunker	0.8.37（版本串 `0.8.37-20261030100830-7667c5056897`，Docker Hub 发布 2026-10-30）
后端数据库	PostgreSQL 16（官方编排指定）
服务端口	容器内 3000，宿主映射 8134
部署目录	`~/databunker-stack`（本文实验目录，下文以 `$PWD` 指代）

二、前置条件

Docker 引擎与 Compose v2+ 可用：docker compose version 有输出。
宿主端口空闲：ss -ltn | grep ':8134 ' 无输出（本文实测环境 3000 端口被占，故取 8134）。
openssl 可用（密钥生成脚本需要）；uuidgen 非必需（见排障实录 1）。
能拉取 securitybunker/databunker:0.8.37（约 46 MB）与 postgres:16。

三、获取官方部署文件

官方把 Compose 编排与密钥脚本放在仓库根目录，共四个文件：

mkdir -p ~/databunker-stack && cd ~/databunker-stack
curl -O https://raw.githubusercontent.com/securitybunker/databunker/master/docker-compose-pgsql.yml
curl -O https://raw.githubusercontent.com/securitybunker/databunker/master/generate-pgsql-env-files.sh
curl -O https://raw.githubusercontent.com/securitybunker/databunker/master/setup-postgresql.sh
curl -O https://raw.githubusercontent.com/securitybunker/databunker/master/databunker.yaml
mv docker-compose-pgsql.yml docker-compose.yml
ls -l

total 16
-rw-r--r-- 1 root root 3241 Nov  3 11:45 databunker.yaml
-rw-r--r-- 1 root root 1203 Nov  3 11:45 docker-compose.yml
-rw-r--r-- 1 root root 1686 Nov  3 11:45 generate-pgsql-env-files.sh
-rw-r--r-- 1 root root  262 Nov  3 11:45 setup-postgresql.sh

四个文件的职责：

docker-compose.yml：三服务编排（postgresql、一次性 databunker-init、常驻 databunker）；
generate-pgsql-env-files.sh：生成 .env/ 下全部密钥文件与 PostgreSQL 自签证书；
setup-postgresql.sh：挂载进 PostgreSQL 的 docker-entrypoint-initdb.d/，首次建库时创建 databunkerdb 库与 bunkeruser 角色；
databunker.yaml：应用配置文件（详解见《Databunker 0.8.37 配置参数详解》）。

四、生成密钥

运行官方脚本：

sh ./generate-pgsql-env-files.sh

真实回显（节选，openssl 生成密钥的行省略）：

generating .env/postgresql-postgres.env
generating .env/postgresql.env
generating .env/databunker.env
generating ssl sertificate for postgres server
-----
writing RSA key
sudo chown 999:0 .env/pg-*
generating .env/databunker-root.env
uuidgen: /lib/x86_64-linux-gnu/libuuid.so.1: version `UUID_2.41' not found (required by uuidgen)
Failed to generate DATABUNKER_ROOTTOKEN

脚本生成 5 个文件，但最后一步 root token 生成失败（排障实录 1）。失败不影响其余密钥，手动补一个即可：

echo "DATABUNKER_ROOTTOKEN=$(cat /proc/sys/kernel/random/uuid)" > .env/databunker-root.env
cat .env/databunker-root.env

DATABUNKER_ROOTTOKEN=6d346d01-c55f-403e-8aa1-7c4e4721f4c1

.env/ 目录最终内容：

文件	内容	用途
`databunker.env`	`DATABUNKER_MASTERKEY`（48 位 hex）、`PGSQL_USER_NAME/PASS/HOST/PORT`	应用主密钥与数据库连接
`databunker-root.env`	`DATABUNKER_ROOTTOKEN`（UUID）	API 根令牌（管理面凭据）
`postgresql.env`	`PGSQL_DATABASE/PGSQL_USER/PGSQL_PASSWORD`	供 `setup-postgresql.sh` 建库建角色
`postgresql-postgres.env`	`POSTGRES_PASSWORD`	PostgreSQL 超级用户口令
`pg-server.crt`/`pg-server.key`	自签证书	PostgreSQL 服务端 SSL

🔐 安全提示：DATABUNKER_MASTERKEY 是全部记录的加密根密钥，丢失即所有数据不可解密；DATABUNKER_ROOTTOKEN 等同 API 最高权限。两者应纳入密钥管理（如 DATABUNKER_MASTERKEY_FILE 指向文件），不要提交进版本库。本文令牌为实验自造值，生产请用脚本重新生成。

五、Compose 编排文件

实测使用的 docker-compose.yml（官方结构 + 三处本地适配）：

name: databunker-0837-stack
version: '3'
services:
  postgresql:
    image: postgres:16
    restart: unless-stopped
    env_file:
      - .env/postgresql-postgres.env
      - .env/postgresql.env
    volumes:
      - pgsql-data:/var/lib/postgresql/data
      - ./setup-postgresql.sh:/docker-entrypoint-initdb.d/setup-postgresql.sh
      - ./.env/pg-server.crt:/var/lib/postgresql/server.crt
      - ./.env/pg-server.key:/var/lib/postgresql/server.key
    command: -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
    networks:
      databunker-net:
        aliases:
          - postgresql
  databunker-init:
    image: securitybunker/databunker:0.8.37
    env_file:
      - .env/databunker.env
      - .env/databunker-root.env
    depends_on:
      - postgresql
    entrypoint: /bin/sh
    command: -c "/bin/busybox sleep 3; /databunker/bin/databunker -init -db databunkerdb"
    networks:
      - databunker-net
  databunker:
    image: securitybunker/databunker:0.8.37
    restart: unless-stopped
    env_file:
      - .env/databunker.env
    entrypoint: /bin/sh
    command: -c "/databunker/bin/databunker -start -db databunkerdb -conf /databunker/conf/databunker.yaml"
    depends_on:
      - postgresql
    ports:
      - 8134:3000
    volumes:
      - ./databunker.yaml:/databunker/conf/databunker.yaml:ro
    networks:
      - databunker-net

volumes:
  pgsql-data:

networks:
  databunker-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.58.0/24

要点解读：

databunker-init 是一次性服务：执行 -init 建表、导入默认法律依据记录后退出（Exited (0)）。密钥（master key/root token）若未通过环境变量提供会在该步自动生成；本编排通过 env_file 预先注入，保证可复现。
常驻服务 databunker 只吃 databunker.env：其中 PGSQL_HOST=postgresql 触发 PostgreSQL 后端（不设则回落 SQLite，见配置详解）。
配置文件以只读方式挂载：./databunker.yaml 覆盖内置默认配置，改配置无需重新打包。
官方原版此处为 image: securitybunker/databunker（latest）、ports: - 3000:3000、无 name/subnet。

六、启动编排

docker compose up -d

真实回显：

 Network databunker-0837-stack_databunker-net Creating 
 Volume databunker-0837-stack_pgsql-data Creating 
 Volume databunker-0837-stack_pgsql-data Creating 
 Network databunker-0837-stack_databunker-net Creating 
 Volume databunker-0837-stack_pgsql-data Created 
 Volume databunker-0837-stack_pgsql-data Created 
 Network databunker-0837-stack_databunker-net Created 
 Network databunker-0837-stack_databunker-net Created 
 Container databunker-0837-stack-postgresql-1 Creating 
 Container databunker-0837-stack-postgresql-1 Created 
 Container databunker-0837-stack-databunker-init-1 Creating 
 Container databunker-0837-stack-databunker-1 Creating 
 Container databunker-0837-stack-databunker-1 Created 
 Container databunker-0837-stack-databunker-init-1 Created 
 Container databunker-0837-stack-postgresql-1 Starting 
 Container databunker-0837-stack-postgresql-1 Started 
 Container databunker-0837-stack-databunker-1 Starting 
 Container databunker-0837-stack-databunker-init-1 Starting 
 Container databunker-0837-stack-databunker-1 Started 
 Container databunker-0837-stack-databunker-init-1 Started

启动后状态（约 30 秒后）：

docker compose ps -a

NAME                                      IMAGE                              COMMAND                  SERVICE           CREATED          STATUS                      PORTS
databunker-0837-stack-databunker-1        securitybunker/databunker:0.8.37   "/bin/sh -c '/databu…"   databunker        32 seconds ago   Up 31 seconds (healthy)     0.0.0.0:8134->3000/tcp, [::]:8134->3000/tcp
databunker-0837-stack-databunker-init-1   securitybunker/databunker:0.8.37   "/bin/sh -c '/bin/bu…"   databunker-init   32 seconds ago   Exited (0) 28 seconds ago   
databunker-0837-stack-postgresql-1        postgres:16                        "docker-entrypoint.s…"   postgresql        32 seconds ago   Up 31 seconds               5432/tcp

databunker 服务状态 (healthy) 来自镜像内置 HEALTHCHECK（health-check.sh 探测 /status，并会按证书存在与否自动切换 HTTP/HTTPS 探测方式）。

七、初始化日志核对

docker compose logs databunker-init

首次部署（空库）真实回显：

databunker-init-1  | 2026/11/03 03:18:52 Databunker version: 0.8.37-20261030100830-7667c5056897
databunker-init-1  | 2026/11/03 03:18:52 Databunker init
databunker-init-1  | 2026/11/03 03:18:52 Master key: ****
databunker-init-1  | 2026/11/03 03:18:52 Init database
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table users
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table userapps
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table xtokens
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table sharedrecords
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table audit
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table requests
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table sessions
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table processingactivities
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table legalbasis
databunker-init-1  | 2026/11/03 03:18:52 PostgreSQL: creating table agreements
databunker-init-1  | 2026/11/03 03:18:52 Creating default legal basis records
databunker-init-1  | 2026/11/03 03:18:52 API Root token: ****

两处细节：

Master key: **** / API Root token: ****：0.8.37 起日志不再回显密钥明文（旧版文档里"从 init 输出抄取密钥"的做法已失效），密钥一律以 env_file 注入为准。
建表日志只在空库首次初始化时出现；重跑 -init 幂等（CREATE TABLE IF NOT EXISTS）。

数据库侧核对：

docker compose exec -T postgresql psql -U bunkeruser -d databunkerdb -c "\dt"

                 List of relations
 Schema |         Name         | Type  |   Owner
--------+----------------------+-------+------------
 public | agreements           | table | bunkeruser
 public | audit                | table | bunkeruser
 public | legalbasis           | table | bunkeruser
 public | processingactivities | table | bunkeruser
 public | requests             | table | bunkeruser
 public | sessions             | table | bunkeruser
 public | sharedrecords        | table | bunkeruser
 public | userapps             | table | bunkeruser
 public | users                | table | bunkeruser
 public | xtokens              | table | bunkeruser
(10 rows)

八、部署验证

8.1 健康检查

curl -s -i http://localhost:8134/v1/status

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Security-Policy: default-src 'self' http: https: data: blob: 'unsafe-inline'
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
Date: Tue, 03 Nov 2026 03:41:21 GMT
Content-Length: 2
Content-Type: text/plain; charset=utf-8

OK

8.2 API 烟测（创建 + 回读）

ROOT=$(grep DATABUNKER_ROOTTOKEN .env/databunker-root.env | cut -d= -f2)
curl -s -X POST http://localhost:8134/v1/user \
  -H "X-Bunker-Token: $ROOT" -H 'Content-Type: application/json' \
  -d '{"first":"John","last":"Doe","login":"johndoe","email":"john.doe@example.com","phone":"+441234567890","password":"q1w2e3r4","custom":"vip"}'

{"status":"ok","token":"a08f15ff-472c-4c6b-0c12-6bfb5228c1f0"}

curl -s -H "X-Bunker-Token: $ROOT" http://localhost:8134/v1/user/login/johndoe

{"status":"ok","token":"a08f15ff-472c-4c6b-0c12-6bfb5228c1f0","data":{"custom":"vip","email":"john.doe@example.com","first":"John","last":"Doe","login":"johndoe","password":"q1w2e3r4","phone":"+441234567890"}}

8.3 静态加密落库核对

到后端数据库直接看 users 表——业务字段全部不可读：

docker compose exec -T postgresql psql -U bunkeruser -d databunkerdb \
  -c "SELECT token, left(loginidx,40) AS loginidx, left(data,64) AS data_head FROM users;"

                token                 |                 loginidx                 |                            data_head                             
--------------------------------------+------------------------------------------+------------------------------------------------------------------
 a08f15ff-472c-4c6b-0c12-6bfb5228c1f0 | wYYWC7FdlEp/Md7hUKAjTNP/kkujgGJSmhBGxiX6 | DCO1+X5gH3UpPQN0hhnaS5gms6P/YeLsEn4JIbLLHbbuVagtcWdlzkBgkty1AXZo
(1 row)

data 列是 AES-256-GCM 密文（base64），loginidx 是 SHA-256 哈希索引——拿到数据库文件本身不构成数据泄露。

九、启用 HTTPS（可选）

Databunker 按"证书文件存在即启用 HTTPS"工作：/databunker/certs/server.cer + server.key 就位后，服务自动以 TLS 监听。

mkdir -p certs
openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
  -subj "/e=admin@example.com/ST=London/L=London/O=Example Ltd./CN=databunker.example.com" \
  -keyout certs/server.key -out certs/server.cer
chmod 644 certs/server.key

🔧 chmod 644 不是可选项：服务进程以非特权用户读取私钥，openssl 默认 0600 权限会直接导致启动失败（排障实录 2）。

给 databunker 服务追加挂载后重建：

    volumes:
      - ./databunker.yaml:/databunker/conf/databunker.yaml:ro
      - ./certs:/databunker/certs:ro

docker compose up -d databunker
docker compose logs --tail=1 databunker

databunker-1  | 2026/11/03 03:42:57 Open HTTPS listener 0.0.0.0:3000

curl -sk https://localhost:8134/v1/status

OK

镜像内置 HEALTHCHECK 会探测证书路径并自动改用 HTTPS 探针（wget --no-check-certificate -q https://localhost:3000/status），无需手工调整。生产建议：用 Let's Encrypt 签发的 fullchain.pem/privkey.pem 分别改名放入 certs/server.cer/server.key（官方安装指南口径）。

十、排障实录

实录 1：官方脚本生成 root token 失败

现象：generate-pgsql-env-files.sh 末行输出 Failed to generate DATABUNKER_ROOTTOKEN，.env/databunker-root.env 未创建。
回显：uuidgen: /lib/x86_64-linux-gnu/libuuid.so.1: version 'UUID_2.41' not found (required by uuidgen)。
根因：脚本依次尝试 uuid/uuidgen 命令，宿主 uuidgen 因 libuuid 版本冲突不可用。
解法：内核随机源等价可用——echo "DATABUNKER_ROOTTOKEN=$(cat /proc/sys/kernel/random/uuid)" > .env/databunker-root.env。

实录 2：HTTPS 启用后服务反复重启

现象：挂载证书后 docker compose ps 显示服务 restarting，日志 ListenAndServeSSL: open /databunker/certs/server.key: permission denied。
根因：私钥文件权限 0600、属主 root，服务进程无读权限，TLS 监听失败进程退出，restart: unless-stopped 反复拉起。
解法：chmod 644 certs/server.key（证书目录只读挂载即可）。修复后日志 Open HTTPS listener 0.0.0.0:3000，curl -k 验证通过。

实录 3：自定义网段冲突

现象：docker compose up 报 Pool overlaps with other one on this address space。
根因：多栈共存环境显式网段被并发占用的窗口期撞车。
解法：docker network inspect $(docker network ls -q) | grep -oE '10\.89\.[0-9]+\.0/24' | sort -u 实查已占段后换用空闲槽位。单栈部署可整段删除 networks 自定义，回落 Compose 默认网络。

十一、日常运维

日志：docker compose logs -f databunker；访问日志形如 [200] POST /v1/user，健康检查请求自动折叠（ignore subsequent /status requests）。
备份：PostgreSQL 后端请用 pg_dump（docker compose exec -T postgresql pg_dump -U bunkeruser databunkerdb > backup.sql）。注意：应用自带 GET /v1/sys/backup 端点对 PostgreSQL 后端返回 200 但 0 字节，仅 SQLite 后端有内容。
升级：改 docker-compose.yml 的应用 tag → docker compose pull → docker compose up -d。跨大版本升级前先 pg_dump；-init 对新表幂等。
改配置：编辑 databunker.yaml 后 docker compose restart databunker 即可（详见《Databunker 0.8.37 配置参数详解》）。
卸载：docker compose down -v（-v 连数据卷一起删除，不可恢复）。

十二、常见问题

Q1：-init 能重复执行吗？ 能。建表语句均为 CREATE TABLE IF NOT EXISTS，实测重跑无副作用；但 root token/master key 必须由 env_file 固定提供，否则每次都会生成新密钥导致旧数据不可解。

Q2：不配 PostgreSQL 可以吗？ 可以。删除 PGSQL_HOST 等变量后服务回落内置 SQLite（数据文件 databunker.db），适合体验与单机小流量场景；官方生产口径推荐 MySQL/PostgreSQL。

Q3：为什么 curl http://localhost:8134/ 返回的是登录页？ 应用内置 Web 自助门户（GDPR 用户端），与 API 同端口。门户登录依赖 SMTP/SMS 网关配置，未配置时仅演示账号可用。

Q4：服务起来但 API 全部 403？ 检查 X-Bunker-Token 是否取自 .env/databunker-root.env（注意实录 1 的失败场景——root token 文件可能根本没生成）。