Bigcapital v0.25.44 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用官方 docker-compose.prod.yml 编排把 Bigcapital v0.25.44 完整跑起来——从克隆仓库、配置 .env、启动九个服务、确认数据库迁移、初始化 S3 对象存储，到注册首个账号并完成组织初始化的全过程。已在 Ubuntu 22.04（内核 6.x、Docker 29.8.1、Compose v5.5.1）实测通过，全部命令与回显均来自真实部署过程。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
应用版本：Bigcapital v0.25.44（2026-10-15 发布，部署时克隆 main 分支，HEAD 为 d2a0bf153a0f11dc4250df504105d3fea74356bd，2026-09-23）
Docker：29.8.1；Docker Compose：v5.5.1
部署目录：/opt/bigcapital（仓库克隆目录，编排与 .env 都在这里）
服务入口：80/443（官方默认，本文环境因端口占用改为 8128/8129，通过 .env 的 PUBLIC_PROXY_PORT/PUBLIC_PROXY_SSL_PORT 覆盖）
组件构成（官方编排共 9 个服务）：

服务	镜像	角色	镜像大小（实测）
proxy	envoyproxy/envoy:v1.30-latest	统一入口反代，暴露 80/443	257MB
webapp	bigcapitalhq/webapp:latest	React 前端（静态站点）	123MB
server	bigcapitalhq/server:latest	NestJS API 服务（内部 3000）	1.91GB
database_migration	基于 bigcapitalhq/server 本地构建	一次性数据库迁移任务	构建产生
mysql	基于 mariadb:10.2 本地构建	系统库 + 各组织业务库	构建产生
redis	基于 redis:6.2.21 本地构建	缓存 + BullMQ 队列	构建产生
clickhouse	clickhouse/clickhouse-server:24.8	财务汇总分析库（可开关）	807MB
garage	dxflrs/garage:v1.3.1	S3 兼容对象存储（附件/文档）	33.1MB
gotenberg	gotenberg/gotenberg:7	发票/单据 PDF 渲染	2.38GB
auto-update	containrrr/watchtower:1.7.1	server/webapp 镜像自动更新	22.4MB

💡 说明：应用本体（server/webapp）不本地构建，直接用官方 CI 推送到 Docker Hub 的成品镜像；mysql/redis/migration 三个服务因带初始化脚本由 compose 在首次 up 时本地构建。磁盘建议预留 10GB 以上（镜像合计约 5.5GB，加数据卷余量）。

二、镜像选型说明

官方 docker-compose.prod.yml 对镜像的策略是「应用用成品、基础件用定制构建」，实测归纳如下：

server / webapp：bigcapitalhq/server:latest、bigcapitalhq/webapp:latest（Docker Hub 官方组织镜像）。官方文档明确写道："we're not going to build docker images of the application from scratch, but docker-compose already imports built images from Github Registry where our continuous-deployment push the new built images when we release new versions"——即镜像由官方 CI 随版本发布自动推送。
mysql / redis / migration：build: 本地构建。mysql 基于 mariadb:10.2 加了 my.cnf 与初始化 SQL；redis 基于 redis:6.2.21 加了定制 redis.conf；migration 基于 bigcapitalhq/server:latest 加了 wait-for-it 与迁移命令，跑完即退出。
clickhouse / garage / gotenberg / envoy / watchtower：直接引用上游镜像，版本由编排文件锁定（24.8 / v1.3.1 / 7 / v1.30-latest / 1.7.1）。

关键差异解读：编排里 server/webapp 用的是 :latest 标签，且配套 watchtower 每小时检查更新——这意味着重复执行 docker compose pull 可能在无意间升级大版本。生产环境建议把两个镜像 tag 固定到具体版本号（如 bigcapitalhq/server:v0.25.44），或按本文第十章关闭 auto-update 服务。

三、前置条件

一台 Ubuntu 22.04 服务器（建议 2 核 4GB 内存起步；本实测机 12 核 31GB）。九个服务中 ClickHouse 与 MySQL/MariaDB 内存占用最大，1GB 内存的机器无法完整跑起。
已安装 Docker 29.x 与 Docker Compose v2+（命令形态 docker compose）。验证方式：

docker --version && docker compose version

实测回显：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

服务器可访问 Docker Hub（拉取官方镜像）。若拉取缓慢，可为 Docker 守护进程配置镜像加速或 HTTP 代理后再继续。
端口规划：默认占用宿主机 80/443（Envoy 入口）。若与既有服务冲突，像本文一样改用 .env 变量换端口（见第四章 4.2 节）。其余服务（MySQL 3306、Redis 6379、ClickHouse 8123、Garage 3900/3903 等）都在编排内部网络里，不对外发布端口，无冲突风险。

四、部署步骤

本章是主线流程：下载 → 配置 → 启动 → 迁移确认 → S3 初始化 → 账号注册 → 端到端验证。每一步都给出实测命令与真实回显。

4.1 下载仓库

官方部署方式是把整个仓库克隆下来，用其中的编排文件、.env.example 与 docker/ 初始化目录：

cd /opt
git clone --depth 1 -b main https://github.com/bigcapitalhq/bigcapital.git bigcapital

实测回显（输出节选）：

Cloning into 'bigcapital'...
remote: Enumerating objects: 13858, done.
remote: Counting objects: 100% (13858/13858), done.
Receiving objects: 100% (13858/13858), 58.34 MiB | 5.20 MiB/s, done.
Updating files: 100% (13806/13806), done.

克隆完成后确认三个关键文件存在：docker-compose.prod.yml（生产编排）、.env.example（环境变量模板）、docker/（mysql/redis/migration 构建上下文与 garage/envoy 配置）。

4.2 配置 .env

从模板复制并按需修改。有四个变量必须填写，缺了编排会拒绝启动（APP_JWT_SECRET、CLICKHOUSE_PASSWORD、GARAGE_RPC_SECRET、GARAGE_ADMIN_TOKEN）：

cd /opt/bigcapital
cp .env.example .env
# 生成各密钥的官方推荐方式
openssl rand -base64 48   # → APP_JWT_SECRET（JWT 签名密钥）
openssl rand -base64 32   # → CLICKHOUSE_PASSWORD（分析库口令）
openssl rand -hex 32      # → GARAGE_RPC_SECRET / GARAGE_ADMIN_TOKEN（对象存储集群密钥与管理令牌）

实测生成示例（本文演示栈实际使用的值，生产环境请重新生成）：

lNZeYWmXRcMGaBFYtd9ty6LODCmVDhdkV43cxS2i81b1baCxYaqNSBOfpCgyZnDL      # APP_JWT_SECRET（base64 48）
dPHFA++phy7oUlxnafHbfuzZlP+WHLsxzJ1EEEZU5oI=                          # CLICKHOUSE_PASSWORD（base64 32）
e987a016d010711e410f6d3e9f80fcde1f1d7d13093e41106225fe7933cf6afb      # GARAGE_RPC_SECRET（hex 32）
acf2987a934459b20162bbca06a4e4b934076c7ac81909ba05aa710726d24588      # GARAGE_ADMIN_TOKEN（hex 32）

本文实测 .env 中其余关键项的最终取值（演示口径，数据库口令按示例口令规范取 q1w2e3r4）：

# 数据库
DB_HOST=mysql
DB_USER=bigcapital
DB_PASSWORD=q1w2e3r4
DB_ROOT_PASSWORD=q1w2e3r4
DB_CHARSET=utf8
SYSTEM_DB_NAME=bigcapital_system
TENANT_DB_NAME_PERFIX=bigcapital_tenant_

# 应用
BASE_URL=http://localhost:8128

# 入口端口（默认 80/443，本环境被占用改为 8128/8129）
PUBLIC_PROXY_PORT=8128
PUBLIC_PROXY_SSL_PORT=8129

# PDF 渲染（生产编排内部服务名）
GOTENBERG_URL=http://gotenberg:3000
GOTENBERG_DOCS_URL=http://server:3000/public/

# S3（先留空，启动后按 4.5 节初始化 Garage 后回填）
S3_REGION=garage
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_ENDPOINT=http://garage:3900
S3_BUCKET=bigcapital
S3_FORCE_PATH_STYLE=true

⚠️ 注意：DB_HOST=mysql、REDIS_HOST=redis 等主机名在 docker-compose.prod.yml 里已写死为服务名，不要改成 IP。数据库口令在 MariaDB 首次初始化时落库，之后改 .env 不会同步——要改口令只能进数据库执行 SQL 或删卷重来（官方文档明确提示了这一点）。

4.3 启动全部服务

cd /opt/bigcapital
docker compose -f docker-compose.prod.yml up -d

实测回显（输出节选，首次执行会先构建 mysql/redis/migration 三个镜像并拉取其余镜像，约 5~15 分钟）：

[+] Running 13/13
 ✔ Network bigcapital-02544-stack_bigcapital_network  Created
 ✔ Container bigcapital-clickhouse     Started
 ✔ Container bigcapital-02544-stack-gotenberg-1  Started
 ✔ Container bigcapital-auto-update    Started
 ✔ Container bigcapital-redis          Started
 ✔ Container bigcapital-mysql          Started
 ✔ Container bigcapital-database-migration  Starting
 ✔ Container bigcapital-webapp         Started
 ✔ Container bigcapital-garage         Started
 ✔ Container bigcapital-server         Started
 ✔ Container bigcapital-02544-stack-proxy-1  Started

用 ps 确认九个服务的运行状态（实测）：

docker compose -f docker-compose.prod.yml ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'

NAME                                 IMAGE                               STATUS
bigcapital-02544-stack-gotenberg-1   gotenberg/gotenberg:7               Up 14 minutes
bigcapital-02544-stack-proxy-1       envoyproxy/envoy:v1.30-latest       Up 14 minutes
bigcapital-auto-update               containrrr/watchtower:1.7.1         Restarting (1) 58 seconds ago
bigcapital-clickhouse                clickhouse/clickhouse-server:24.8   Up 14 minutes
bigcapital-garage                    dxflrs/garage:v1.3.1                Up 14 minutes
bigcapital-mysql                     bigcapital-02544-stack-mysql        Up 14 minutes
bigcapital-redis                     bigcapital-02544-stack-redis        Up 14 minutes
bigcapital-server                    bigcapitalhq/server:latest          Up About a minute (healthy)
bigcapital-webapp                    bigcapitalhq/webapp:latest          Up 14 minutes

⚠️ 注意：auto-update（watchtower）在较新的 Docker 版本上会反复重启，报错为 "client version 1.25 is too old. Minimum supported API version is 1.40"。它不影响业务服务运行，修复方法见第十一章 FAQ Q1。

4.4 确认数据库迁移

编排内的 database_migration 是一次性任务：等 MySQL 就绪后自动执行系统库与租户库迁移，然后退出。用日志确认（实测）：

docker logs bigcapital-database-migration

wait-for-it.sh: waiting 15 seconds for mysql:3306
wait-for-it.sh: mysql:3306 is available after 6 seconds
Batch 1 run: 31 migrations
All tenants are migrated.

看到 Batch 1 run: 31 migrations 与 All tenants are migrated. 即迁移成功（官方文档示例是 6 个迁移，v0.25.x 已增长到 31 个，以实际输出为准）。

4.5 初始化 Garage 对象存储（S3 密钥）

Bigcapital 的附件/文档存 S3，官方编排用 Garage 承担该角色。.env.example 注释给出的初始化命令是 docker compose exec garage bash /garage-setup/setup.sh，但实测 dxflrs/garage:v1.3.1 镜像内没有 bash、没有 sh（纯二进制镜像），该命令会报错：

OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH

解决办法是直接 exec 镜像内的 /garage CLI，按 setup.sh 的逻辑逐条执行（效果等同且幂等）。

第一步，确认节点并分配存储角色：

docker exec bigcapital-garage /garage status
docker exec bigcapital-garage /garage node id
docker exec bigcapital-garage /garage layout assign <上一步输出的节点ID前16位> -z dc1 -c 10G
docker exec bigcapital-garage /garage layout apply --version 1

实测回显（输出节选）：

==== HEALTHY NODES ====
ID                Hostname      Address          Tags  Zone  Capacity          DataAvail
e09a40146505160a  3fd8816ed105  10.89.66.8:3901              NO ROLE ASSIGNED
...
New cluster layout with updated role assignment has been applied in cluster.
==== HEALTHY NODES ====
ID                Hostname      Address          Tags  Zone  Capacity  DataAvail
e09a40146505160a  3fd8816ed105  10.89.66.8:3901  []    dc1   10.0 GB   391.8 GB (46.4%)

第二步，创建 S3 访问密钥与存储桶并授权（实测）：

docker exec bigcapital-garage /garage key create bigcapital
docker exec bigcapital-garage /garage bucket create bigcapital
docker exec bigcapital-garage /garage bucket allow bigcapital --key bigcapital --owner --read --write

Secret key: e2cc1447300b16d23d283494fbad9b9c288af36685474f5828395fe2dcb59618
Bucket bigcapital was created.
New permissions for GK6082cef2f780f8e2b56461c8 on bigcapital: read true, write true, owner true.

⚠️ 注意：garage key create 用位置参数（garage key create bigcapital），bucket allow 的桶名也是位置参数（garage bucket allow bigcapital --key ...）。setup.sh 里写的 key create --name 与 --bucket 写法在 v1.3.1 上不兼容，直接照抄 setup.sh 会报 USAGE 错误。

第三步，把密钥回填进 .env 并重启 server（官方变更 .env 的标准做法就是重启容器）：

S3_ACCESS_KEY_ID=GK6082cef2f780f8e2b56461c8
S3_SECRET_ACCESS_KEY=e2cc1447300b16d23d283494fbad9b9c288af36685474f5828395fe2dcb59618

docker compose -f docker-compose.prod.yml restart server

重启后确认回到 healthy（实测）：

bigcapital-server   bigcapitalhq/server:latest   ...   Up 15 seconds (healthy)   3000/tcp

4.6 注册首个账号

Bigcapital 无默认账号，首个账号决定管理权。通过入口（Envoy）调用注册接口（实测；也可直接在浏览器打开 http://<服务器IP>:8128/ 点 Sign Up）：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"email":"admin@bigcapital.local","password":"q1w2e3r4t6","first_name":"Admin","last_name":"User","phone_number":"13800000000"}' \
  http://127.0.0.1:8128/api/auth/signup

实测回显：

{"user_id":1,"tenant_id":1,"organization_id":"11rxmx1mvjt993z"}

⚠️ 注意：口令最少 10 位（q1w2e3r4 只有 8 位会被拒："password must be longer than or equal to 10 characters"），本文演示用 q1w2e3r4t6。若 .env 开了 SIGNUP_EMAIL_CONFIRMATION=true，注册后需先完成邮箱验证。

4.7 登录并完成组织初始化（租户库构建）

登录拿访问令牌，再触发组织构建——这一步会创建该组织的独立业务库（实测）：

# 登录
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"email":"admin@bigcapital.local","password":"q1w2e3r4t6"}' \
  http://127.0.0.1:8128/api/auth/signin

实测回显：

{"access_token":"eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzkyNjg5NTI5LCJleHAiOjE3OTI3NzU5MjksImF1ZCI6ImJpZ2NhcGl0YWw6YXBpIiwiaXNzIjoiYmlnY2FwaXRhbCJ9.zILN9Ho7fYra1YeSgzslnYra6kX2U-aT0CvCr4Cs38CxItr5oWr8KHCHDxL6NStB","organization_id":"11rxmx1mvjt993z","tenant_id":1,"user_id":1}

# 组织初始化（替换 TOKEN 与 organization-id 为上一步实际值）
curl -s -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "organization-id: 11rxmx1mvjt993z" \
  -d '{"name":"Demo Company","location":"CN","base_currency":"CNY","timezone":"Asia/Shanghai","fiscal_year":"january","language":"en"}' \
  http://127.0.0.1:8128/api/organization/build

实测回显：

{"type":"success","code":"ORGANIZATION.DATABASE.INITIALIZED","message":"The organization database has been initialized.","data":{"job_id":"1"}}

到 MySQL 里验证租户库已生成（实测）：

docker exec bigcapital-mysql sh -c 'mysql -ubigcapital -pq1w2e3r4 -e "SHOW DATABASES LIKE \"bigcapital_tenant%\";"'

Database (bigcapital_tenant%)
bigcapital_tenant_11rxmx1mvjt993z

4.8 最终验证

浏览器打开 http://<服务器IP>:8128/（官方默认部署为 http://<服务器IP>:80/），应看到 Bigcapital 登录页；用 4.6 节注册的 admin@bigcapital.local / q1w2e3r4t6 登录即可进入工作台。

命令行验证入口与前端（实测）：

curl -sI http://127.0.0.1:8128/ | head -4

HTTP/1.1 200 OK
server: envoy
date: Thu, 22 Oct 2026 17:13:40 GMT
content-type: text/html

五、数据持久化说明

官方编排用四个命名卷持久化数据，实测卷清单：

bigcapital_prod_clickhouse
bigcapital_prod_garage
bigcapital_prod_mysql
bigcapital_prod_redis

卷	容器内路径	内容
bigcapital_prod_mysql	/var/lib/mysql	系统库 + 全部组织业务库（核心财务数据）
bigcapital_prod_redis	/data	队列/缓存（可丢失，重启自动恢复）
bigcapital_prod_garage	/var/lib/garage	附件与文档对象
bigcapital_prod_clickhouse	/var/lib/clickhouse	财务汇总分析数据

要点：

卷由 compose 项目管理，docker compose down 不删卷，down -v 才删——财务数据在 mysql 卷里，任何清理操作前先确认。
备份最小集：mysql 卷（mysqldump 逻辑备份或停机快照）+ garage 卷（附件）。ClickHouse 数据可由 CLICKHOUSE_ENABLED=false 场景降级为不启用。
Garage 初始化脚本支持 GARAGE_CAPACITY 环境变量调整单节点容量（默认 10G），扩容后重新 layout apply。

六、环境变量表

以下为首次部署必须理解的核心变量（完整清单见仓库 .env.example，158 行，全部变量说明见本专栏《Bigcapital v0.25.44 配置参数详解》）：

变量	必填	实测取值	说明
APP_JWT_SECRET	是	`openssl rand -base64 48` 生成	JWT 签名密钥，编排校验非空才启动
CLICKHOUSE_PASSWORD	是	`openssl rand -base64 32` 生成	分析库口令，编排校验非空才启动
GARAGE_RPC_SECRET	是	`openssl rand -hex 32` 生成	Garage 集群 RPC 密钥
GARAGE_ADMIN_TOKEN	是	`openssl rand -hex 32` 生成	Garage 管理 API 令牌
DB_USER / DB_PASSWORD	是	bigcapital / q1w2e3r4	MariaDB 业务账号（首次初始化落库）
DB_ROOT_PASSWORD	是	q1w2e3r4	MariaDB root 口令
SYSTEM_DB_NAME	是	bigcapital_system	系统库名
TENANT_DB_NAME_PERFIX	是	bigcapital_tenant_	组织库前缀（官方拼写即 PERFIX）
BASE_URL	是	http://localhost:8128	对外访问地址（影响链接生成）
PUBLIC_PROXY_PORT / PUBLIC_PROXY_SSL_PORT	否	8128 / 8129（默认 80/443）	Envoy 入口端口
GOTENBERG_URL	是	http://gotenberg:3000	PDF 渲染服务地址
SIGNUP_DISABLED	否	false	关闭注册（建好账号后建议 true）
SIGNUP_EMAIL_CONFIRMATION	否	false	注册邮箱验证开关
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY	是（附件功能）	4.5 节生成	Garage S3 密钥
THROTTLE_GLOBAL_LIMIT / THROTTLE_AUTH_LIMIT	否	300 / 30	全局与认证接口限流（60 秒窗口）
AUTO_UPDATE_INTERVAL	否	3600	watchtower 轮询间隔（秒）

七、配置参数说明

编排文件本身可按需调整的关键参数（均在 docker-compose.prod.yml）：

网络：bigcapital_network 默认 bridge 随机网段。多套栈并存时建议显式固定子网，避免网段漂移：

networks:
  bigcapital_network:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.66.0/24

项目名：多套部署共存时在编排顶部显式命名，防止 down 时误删同名项目：

name: bigcapital-0.25.44-stack

重启策略：核心服务均为 restart: on-failure（proxy/mysql/redis/server/webapp/garage/clickhouse/auto-update 全覆盖），宿主机重启后 compose 未自动拉起时手动 docker compose -f docker-compose.prod.yml up -d。
auto-update 服务：负责 server/webapp 两个 latest 镜像的自动升级，command: --label-enable --cleanup --interval ${AUTO_UPDATE_INTERVAL:-3600}。不希望自动升级就注释掉该服务块。

八、配置文件挂载

官方编排中的挂载点一览（实测清单，均相对仓库根目录）：

挂载	去向	用途
./docker/envoy/envoy.yaml	/etc/envoy/envoy.yaml	入口路由：`/api` → server:3000，其余 → webapp:80
./docker/garage/garage.toml	/etc/garage.toml	Garage 节点配置（RPC/管理端口等）
./docker/garage/setup.sh	/garage-setup/setup.sh	初始化脚本（因镜像无 shell 需按 4.5 节手工执行）
./docker/mariadb/{my.cnf,init.sql,docker-entrypoint.sh}	构建进镜像	MariaDB 字符集与首次建库初始化
./docker/redis/redis.conf	构建进镜像	Redis 定制配置
./docker/migration/Dockerfile	构建上下文	迁移任务镜像（wait-for-it + 迁移命令）

💡 说明：调整入口路由（如加 HTTPS、改路径）就编辑 docker/envoy/envoy.yaml 后 docker compose -f docker-compose.prod.yml restart proxy；调整 MariaDB 参数则改 docker/mariadb/my.cnf 后需要 up --build 重建。

九、等价 docker run

理解编排的最小方式：每个服务等价于一条 docker run（演示网络与卷名按本项目实际值）。以下为核心服务的等价命令（mysql/redis 因本地构建镜像名为 <项目>-mysql/<项目>-redis，此处以实际镜像名代替）：

# 入口代理（路由配置挂载）
docker run -d --name bigcapital-proxy \
  -p 8128:80 -p 8129:443 \
  -v /opt/bigcapital/docker/envoy/envoy.yaml:/etc/envoy/envoy.yaml \
  --network bigcapital-02544-stack_bigcapital_network \
  envoyproxy/envoy:v1.30-latest

# API 服务（连接 mysql/redis，注入 .env 全部业务变量）
docker run -d --name bigcapital-server \
  -e DB_HOST=mysql -e DB_USER=bigcapital -e DB_PASSWORD=q1w2e3r4 \
  -e SYSTEM_DB_NAME=bigcapital_system \
  -e REDIS_HOST=redis -e QUEUE_HOST=redis \
  -e APP_JWT_SECRET=lNZeYWmXRcMGaBFYtd9ty6LODCmVDhdkV43cxS2i81b1baCxYaqNSBOfpCgyZnDL \
  --network bigcapital-02544-stack_bigcapital_network \
  bigcapitalhq/server:latest

# 前端
docker run -d --name bigcapital-webapp \
  --network bigcapital-02544-stack_bigcapital_network \
  bigcapitalhq/webapp:latest

# 数据库（数据卷持久化）
docker run -d --name bigcapital-mysql \
  -e MYSQL_DATABASE=bigcapital_system \
  -e MYSQL_USER=bigcapital -e MYSQL_PASSWORD=q1w2e3r4 -e MYSQL_ROOT_PASSWORD=q1w2e3r4 \
  -v bigcapital_prod_mysql:/var/lib/mysql \
  --network bigcapital-02544-stack_bigcapital_network \
  bigcapital-02544-stack-mysql

💡 说明：compose 的价值在于把环境变量注入、健康等待（server 依赖 mysql/redis/garage）与迁移任务编排成一体，生产请以 compose 为准，docker run 仅用于理解与临时调试。

十、常用运维命令

以下命令均在 /opt/bigcapital 目录下执行，-f docker-compose.prod.yml 可用 alias 简化（实测环境统一带全参数）。

# 查看服务状态
docker compose -f docker-compose.prod.yml ps

# 跟踪某个服务日志（如 server）
docker compose -f docker-compose.prod.yml logs -f server

# 重启单个服务（改 .env 后生效的标准动作）
docker compose -f docker-compose.prod.yml restart server

# 拉取镜像更新并滚动重建（官方升级路径）
git pull origin main
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up --build -d

# 进入数据库执行 SQL
docker exec -it bigcapital-mysql sh -c 'mysql -ubigcapital -pq1w2e3r4 bigcapital_system'

# 查看对象存储桶内容
docker exec bigcapital-garage /garage bucket info bigcapital

# 停止与启动整栈
docker compose -f docker-compose.prod.yml down    # 保留数据卷
docker compose -f docker-compose.prod.yml up -d   # 再次启动

⚠️ 注意：down -v 会删除四个数据卷（含全部财务数据），执行前必须确认备份。

十一、常见问题（FAQ）

Q1：auto-update（watchtower）反复重启，日志报 "client version 1.25 is too old"？

实测报错：

level=error msg="Error response from daemon: client version 1.25 is too old. Minimum supported API version is 1.40, please upgrade your client to a newer version"

原因：watchtower 1.7.1 默认以 Docker API 1.25 连接守护进程，新版 Docker（25+）已把最低兼容版本提到 1.40。修复：给 auto-update 服务加环境变量指定新版本 API。验证过的一次性运行（实测成功）：

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e DOCKER_API_VERSION=1.44 containrrr/watchtower:1.7.1 --run-once --label-enable

level=info msg="Session done" Failed=0 Scanned=2 Updated=0 notify=no

即在 docker-compose.prod.yml 的 auto-update 服务下加：

    environment:
      - DOCKER_API_VERSION=1.44

Q2：执行 docker compose exec garage bash ... 报 "bash: executable file not found"？

Garage 官方镜像（dxflrs/garage）是纯二进制镜像，没有任何 shell。按本文 4.5 节用 docker exec bigcapital-garage /garage <子命令> 逐条执行等价初始化即可；子命令语法以 garage --help 为准（v1.3.1 的 key create/bucket allow 与 setup.sh 中的写法不一致）。

Q3：.env 里 BANK_FEED_ENABLED / NEW_RELIC_ 提示 "variable is not set"？*

执行 compose 命令时的一串 warning，属正常现象：.env.example 未包含这些键而编排有引用，缺省为空字符串即关闭对应功能（银行同步、New Relic 监控）。想消除提示就在 .env 里显式补 BANK_FEED_ENABLED=false 等空值键。

Q4：注册接口返回 "password must be longer than or equal to 10 characters"？

口令最短 10 位。把示例口令从 q1w2e3r4 换成 q1w2e3r4t6 这类 10 位以上口令。

Q5：/api/organization/build 返回 "Organization ID is required"？

多租户认证需要同时携带 Authorization: Bearer <token> 与 organization-id: <组织ID> 两个请求头；组织 ID 取登录响应里的 organization_id 字段。构建接口还要求组织信息必填齐全：name、location（ISO 3166-1 两位码）、base_currency（ISO 4217）、timezone（IANA 时区名）、fiscal_year（小写月份名，如 january）、language（en 或 ar）。

Q6：迁移任务失败如何排查？

先看迁移容器日志：docker logs bigcapital-database-migration。常见两类：① wait-for-it.sh: timeout occurred——MySQL 尚未就绪，检查 docker logs bigcapital-mysql 是否有初始化报错；② 迁移 SQL 报错——多因残留旧卷与新版本不匹配，确认是否需要按官方文档回滚到对应版本卷。

Q7：80/443 端口被占用？

不用改编排文件，在 .env 里设 PUBLIC_PROXY_PORT=8128、PUBLIC_PROXY_SSL_PORT=8129 后 up -d 重建 proxy 即可（本文全程即按 8128/8129 实测）。

十二、参考链接

官方 Docker 部署指南（本篇流程依据）：https://docs.bigcapital.app/deployment/docker
官方环境变量说明：https://docs.bigcapital.app/deployment/env_vars
仓库编排文件：https://github.com/bigcapitalhq/bigcapital/blob/main/docker-compose.prod.yml
Garage 对象存储文档：https://garagehq.deuxfleurs.fr/documentation/
本专栏相关文档：《Bigcapital v0.25.44 介绍与选型指南》、《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》、《Bigcapital v0.25.44 配置参数详解》