Dolibarr 24.0 Docker Compose 部署指南

Docker Compose 编排 Dolibarr 24.0.2 + MariaDB 10.11 实测：一键启动与自动初始化、三目录数据持久化与 down/up 恢复验证、环境变量表、conf.php 生成机制、等价 docker run、备份升级与常见问题。

DolibarrDolibarrERPDockerDocker Compose2026/10/23

Dolibarr 24.0 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用 Docker Compose 编排 Dolibarr 24.0.2 与 MariaDB 10.11 两个服务，实现一键启动、数据库自动初始化、管理员账号自动创建、数据持久化与重启恢复验证。已在 Ubuntu 22.04（Docker 29.8.1、Docker Compose v5.5.1）实测通过，全部命令与回显均来自真实部署过程并逐行照抄。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Docker 版本：29.8.1；Docker Compose：v5.5.1（docker compose 插件形态）
  • 应用版本：Dolibarr 24.0.2（官方镜像 dolibarr/dolibarr:24.0.2）
  • 数据库版本：MariaDB 10.11（官方镜像 mariadb:10.11，实测容器内版本 10.11.19）
  • PHP 版本：8.5.12（应用镜像内置，Dolibarr 所需扩展已全部就绪）
  • 部署目录：/opt/dolibarr
  • 服务入口：宿主机 8147 → Web 服务 80
  • 数据持久化目录：/opt/dolibarr/data/（mariadb/、documents/、custom/ 三个子目录）
  • 编排项目名：dolibarr-24.0.2-stack（compose 文件内显式 name: 声明）

二、镜像选型说明

Dolibarr 官方在 Docker Hub 维护 dolibarr/dolibarr 镜像（源码仓库 Dolibarr/dolibarr-docker），应用镜像内已集成 Apache + PHP + 全部所需 PHP 扩展，因此编排里只需两个服务：应用 + 数据库。实测镜像版本与体积如下：

镜像版本实测体积角色
dolibarr/dolibarr:24.0.224.0.2（当前最新稳定版）1.39GB应用本体（Apache + PHP 8.5 + Dolibarr 程序 + 启动脚本）
mariadb:10.1110.11.19（实测）459MB数据库

💡 技术拓展：Dolibarr 不绑定单一数据库，mysqli 与 pgsql 两种 DOLI_DB_TYPE 均受支持。常见选择对比——

数据库镜像特点适用场景
MariaDB 10.11mariadb:10.11MySQL 的社区分支，Dolibarr 官方镜像示例与文档默认通用首选，本文实测方案
MySQL 8.xmysql:8.4与 MariaDB 同源，功能等价已有 MySQL 运维体系的团队
PostgreSQL 15+postgres:16需把 DOLI_DB_TYPE 改为 pgsql已有 PG 运维体系/需要 PG 生态特性

本文实际采用 MariaDB 10.11，理由：Dolibarr 官方安装文档与镜像示例均以 MariaDB/MySQL 为主线，兼容性验证最充分，且 mariadb-dump 备份工具链开箱即用。

镜像标签选择建议：

标签说明
24.0.2锁定到具体补丁版本，生产推荐——升级可控
24.0跟随 24.0.x 补丁滚动，pull 时可能自动升级小版本
latest随上游漂移，可能跨大版本，生产禁用

关键差异解读：生产环境务必锁定 24.0.2 这类完整版本号；docker compose pull 对 latest/24.0 标签会静默拉新版本，配合 up -d 就完成了计划外升级。

三、前置条件

  1. 一台 Ubuntu 22.04 服务器，2 核 4GB 内存起步（本实测机资源充裕；Dolibarr + MariaDB 空载常驻内存约 500MB，预留 2GB 以上余量更稳）。
  2. 已安装 Docker Engine 与 Compose 插件，验证方式：
docker --version && docker compose version

实测输出：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1
  1. 端口规划：宿主机 8147 未被占用。检查方式：
ss -ltn | grep 8147 || echo "8147 free"

实测输出：

8147 free
  1. 若服务器可访问外网，docker compose pull 直接拉取官方镜像即可。

四、部署步骤

4.1 创建部署目录

sudo mkdir -p /opt/dolibarr/data
cd /opt/dolibarr

三个数据子目录（data/mariadb、data/documents、data/custom）不需要预先创建，首次启动时由服务自动生成（见 4.4 实测）。

4.2 编写 docker-compose.yml

将以下内容保存为 /opt/dolibarr/docker-compose.yml：

name: dolibarr-24.0.2-stack

services:
  mariadb:
    image: mariadb:10.11
    container_name: dolibarr-2402-mariadb
    environment:
      MARIADB_ROOT_PASSWORD: q1w2e3r4          # 数据库 root 密码（演示值，生产请更换）
      MARIADB_DATABASE: dolibarr               # 首次启动自动创建的库名
      MARIADB_USER: dolidbuser                 # 业务账号
      MARIADB_PASSWORD: dolidbpass             # 业务账号密码（与下方 DOLI_DB_PASSWORD 一致）
    volumes:
      - ./data/mariadb:/var/lib/mysql          # 数据库文件持久化
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  web:
    image: dolibarr/dolibarr:24.0.2
    container_name: dolibarr-2402-web
    depends_on:
      mariadb:
        condition: service_healthy             # 等数据库健康检查通过再启动应用
    environment:
      DOLI_DB_HOST: mariadb                    # 数据库主机=compose 服务名（内置 DNS 解析）
      DOLI_DB_HOST_PORT: 3306
      DOLI_DB_NAME: dolibarr
      DOLI_DB_USER: dolidbuser
      DOLI_DB_PASSWORD: dolidbpass
      DOLI_URL_ROOT: http://192.168.146.128:8147   # 外部访问地址，改成你的服务器 IP/域名
      DOLI_ADMIN_LOGIN: admin                  # 自动创建的管理员账号
      DOLI_ADMIN_PASSWORD: q1w2e3r4            # 管理员密码（演示值，生产请更换）
      DOLI_INSTALL_AUTO: 1                     # 首次启动自动建表+装演示基线数据
      DOLI_PROD: 1                             # 生产模式（写入 conf.php 的 prod 标志）
      PHP_INI_DATE_TIMEZONE: Asia/Shanghai     # PHP 时区
      PHP_INI_MEMORY_LIMIT: 512M               # PHP 内存上限
      PHP_INI_UPLOAD_MAX_FILESIZE: 50M         # 单文件上传上限
      PHP_INI_POST_MAX_SIZE: 55M               # POST 包体上限（略大于上传上限）
    ports:
      - "8147:80"
    volumes:
      - ./data/documents:/var/www/documents    # 上传文档/生成文件持久化
      - ./data/custom:/var/www/html/custom     # 外部模块目录持久化
    restart: unless-stopped

配置要点解读：

  • name: dolibarr-24.0.2-stack：显式声明 compose 项目名。多套部署共存的服务器上，项目名决定资源（网络、容器）的归属前缀，避免 down 误删其他项目的资源；
  • depends_on + condition: service_healthy：Dolibarr 首次启动要连库建表，必须等 MariaDB 真正可用（healthcheck 通过），仅写 depends_on: [mariadb] 只保证启动顺序、不保证可用性；
  • MARIADB_PASSWORD 与 DOLI_DB_PASSWORD 必须一致，这是应用连库的凭据；
  • DOLI_URL_ROOT 要与用户浏览器实际访问地址完全一致（含端口），否则登录后生成的链接会指向错误地址；
  • 三个 bind mount 各司其职：数据库文件、上传文档、外部模块目录，全部落在宿主机 ./data/ 下，down 不会丢数据。

4.3 拉取镜像并启动

cd /opt/dolibarr
docker compose pull
docker compose up -d

docker compose pull 实测输出：

 Image mariadb:10.11 Pulling
 Image dolibarr/dolibarr:24.0.2 Pulling
 Image mariadb:10.11 Pulled
 Image dolibarr/dolibarr:24.0.2 Pulled

docker compose up -d 实测输出（MariaDB 健康检查通过后 web 才启动，符合编排约定）：

 Network dolibarr-24.0.2-stack_default Creating
 Network dolibarr-24.0.2-stack_default Created
 Container dolibarr-2402-mariadb Creating
 Container dolibarr-2402-mariadb Created
 Container dolibarr-2402-mariadb Starting
 Container dolibarr-2402-mariadb Started
 Container dolibarr-2402-mariadb Waiting
 Container dolibarr-2402-mariadb Healthy
 Container dolibarr-2402-web Starting
 Container dolibarr-2402-web Started

确认两个服务状态：

docker compose ps

实测输出：

NAME                    IMAGE                      COMMAND                   SERVICE   CREATED       STATUS                 PORTS
dolibarr-2402-mariadb   mariadb:10.11              "docker-entrypoint.s…"   mariadb   3 hours ago   Up 3 hours (healthy)   3306/tcp
dolibarr-2402-web       dolibarr/dolibarr:24.0.2   "docker-run.sh apach…"   web       3 hours ago   Up 3 hours             0.0.0.0:8147->80/tcp, [::]:8147->80/tcp

关键状态解读：mariadb 必须是 Up (healthy)（healthcheck 生效），web 的端口映射 0.0.0.0:8147->80 存在即对外可访问。

4.4 观察自动初始化过程

DOLI_INSTALL_AUTO: 1 时，Web 服务的启动脚本会在首次启动时自动完成建表、写入基线常量、创建管理员。查看初始化日志：

docker compose logs web

实测输出节选（实测首尾）：

dolibarr-2402-web  | docker-run.sh started
dolibarr-2402-web  | [INIT] => update PHP Config ...
dolibarr-2402-web  | [INIT] => update Dolibarr Config ...
dolibarr-2402-web  | mkdir: cannot create directory '/var/www/html/conf': File exists
dolibarr-2402-web  | [INIT] => update Dolibarr Config with instance unique id ...
dolibarr-2402-web  | [INIT] => update ownership for file in Dolibarr Config ...
dolibarr-2402-web  | Current Version of files is : 24.0.2
dolibarr-2402-web  | DOLI_INSTALL_AUTO is on, so we check to initialize or upgrade mariadb database
dolibarr-2402-web  | DB Exists is : dolibarr
dolibarr-2402-web  | Install.lock Exists is : no
dolibarr-2402-web  | No table found, we launch initializeDatabase
dolibarr-2402-web  | Importing table from llx_accounting_account.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_analytic_account-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_analytic_axis-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_analytic_distribution-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_balance_snapshot-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_bookkeeping-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_bookkeeping_piece-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_bookkeeping_tmp-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_category_account-accounting.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_fiscalyear.sql ...
dolibarr-2402-web  | Importing table from llx_accounting_groups_account.sql ...

输出节选说明：建表过程会逐张导入 400 余张 llx_ 前缀数据表，日志有数百行，此处保留首尾关键行。整段导入约 1 分钟完成。

其中 mkdir: cannot create directory '/var/www/html/conf': File exists 是启动脚本的幂等探测输出，目录已存在时必然出现，无害，可忽略。

初始化明细同时落在持久化目录的 initdb.log 里：

cat /opt/dolibarr/data/documents/initdb.log

实测输出节选（实测首尾）：

--------------
mysql  Ver 15.1 Distrib 10.11.19-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

Connection id:          3
Current database:
Current user:           dolidbuser@10.0.1.3
SSL:                    Not in use
Current pager:          stdout
Using outfile:          ''
Using delimiter:        ;
Server:                 MariaDB
Server version:         10.11.19-MariaDB-ubu2204 mariadb.org binary distribution
Protocol version:       10
Connection:             mariadb via TCP/IP
Server characterset:    utf8mb4
Db     characterset:    utf8mb4
Client characterset:    latin1
Conn.  characterset:    latin1
TCP port:               3306
Uptime:                 1 sec

Threads: 1  Questions: 4  Slow queries: 0  Opens: 17  Open tables: 10  Queries per second avg: 4.000
--------------

mysql -u dolidbuser -pxxxxxx -h mariadb -P 3306 -e "SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = 'dolibarr';" > /tmp/docker-run-checkdb.result 2>&1
DB Exists is : dolibarr
Install.lock Exists is : yes

4.5 验证部署结果

第一步，HTTP 层验证（HTTP 200 + 登录页标题带版本号）：

curl -sI http://127.0.0.1:8147/ | head -12
curl -s http://127.0.0.1:8147/ | grep -oE '<title>[^<]*</title>'

实测输出：

HTTP/1.1 200 OK
Date: Fri, 23 Oct 2026 00:33:58 GMT
Server: Apache
Set-Cookie: DOLSESSID_9a96599003f015a153d9d6a89c2a7f2276f5f83f=2ef8724e4abb239e202b1c87b2385913; path=/; HttpOnly; SameSite=Lax
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: Public, must-revalidate
Pragma: no-cache
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: same-origin
Content-Type: text/html; charset=UTF-8

<title>Login @ 24.0.2</title>

第二步，数据库层验证（建表数量与管理员账号）：

docker compose exec mariadb mariadb -udolidbuser -pdolidbpass dolibarr \
  -e "SELECT COUNT(*) AS tables_total FROM information_schema.tables WHERE table_schema='dolibarr'; SELECT login, pass, admin FROM llx_user WHERE admin=1;"

实测输出：

tables_total
410
login   pass    admin
admin   NULL    1

输出解读：410 张表说明自动建表完整；管理员 admin 已创建且 admin=1；pass 列为 NULL 是正常的——24.0 起密码统一存 pass_crypted 哈希列（可再查 pass_crypted 确认为非空哈希值）。

第三步，确认自动生成的应用配置与 PHP 配置：

docker compose exec web sh -c 'cat /var/www/html/conf/conf.php | grep -vE "^\s*$|^\s*#"'
docker compose exec web sh -c 'cat /usr/local/etc/php/conf.d/dolibarr-php.ini'

实测输出（conf.php，由启动脚本按环境变量自动生成）：

<?php
$dolibarr_main_url_root='http://192.168.146.128:8147';
$dolibarr_main_document_root='/var/www/html';
$dolibarr_main_url_root_alt='/custom';
$dolibarr_main_document_root_alt='/var/www/html/custom';
$dolibarr_main_data_root='/var/www/documents';
$dolibarr_main_db_port='3306';
$dolibarr_main_db_name='dolibarr';
$dolibarr_main_db_prefix='llx_';
$dolibarr_main_db_user='dolidbuser';
$dolibarr_main_db_pass='dolidbpass';
$dolibarr_main_db_type='mysqli';
$dolibarr_main_authentication='dolibarr';
$dolibarr_main_prod=1;
$dolibarr_main_db_host='mariadb';
$dolibarr_main_instance_unique_id='myinstanceuniquekey';
$dolibarr_main_db_character_set='utf8mb4';
$dolibarr_main_db_collation='utf8mb4_unicode_ci';

实测输出（PHP 覆盖配置，来源即 compose 里的 PHP_INI_* 环境变量）：

date.timezone = Asia/Shanghai
memory_limit = 512M
upload_max_filesize = 50M
post_max_size = 55M

第四步，浏览器访问 http://<服务器IP>:8147/，使用 admin / q1w2e3r4 登录即可进入 Dolibarr 后台。

五、数据持久化说明

首次启动后，宿主机 /opt/dolibarr/data/ 下会生成三个数据目录，结构如下：

/opt/dolibarr/data/
├── mariadb/      # 数据库文件（ibdata、ib_logfile、dolibarr 库目录等）
├── documents/    # Dolibarr 数据根（install.lock、initdb.log、users/ 上传目录）
└── custom/       # 外部模块目录（默认空）

实测确认（首次启动后）：

ls -la /opt/dolibarr/data/documents/

实测输出：

total 16
drwxr-xr-x 3 www-data www-data 4096 Oct 22 21:21 .
drwxr-xr-x 5 root     root     4096 Oct 22 21:20 .
-rw-r--r-- 1 www-data www-data  900 Oct 22 21:22 initdb.log
-r-------- 1 www-data www-data    0 Oct 22 21:21 install.lock
drwxrwx--x 3 www-data www-data 4096 Oct 22 21:21 users

⚠️ 注意：install.lock（0 字节、仅 www-data 可读）是生产模式锁——它存在时安装/升级页面被禁用。绝不能删除，否则任何人都能访问 /install/ 重装或破坏数据库。

持久化验证：整套 down（删除容器与网络）后重新 up，数据必须原样恢复。实测全过程：

cd /opt/dolibarr
docker compose down

实测输出：

 Container dolibarr-2402-web Stopping
 Container dolibarr-2402-web Stopped
 Container dolibarr-2402-web Removing
 Container dolibarr-2402-web Removed
 Container dolibarr-2402-mariadb Stopping
 Container dolibarr-2402-mariadb Stopped
 Container dolibarr-2402-mariadb Removing
 Container dolibarr-2402-mariadb Removed
 Network dolibarr-24.0.2-stack_default Removing
 Network dolibarr-24.0.2-stack_default Removed

docker compose up -d

实测输出：

 Network dolibarr-24.0.2-stack_default Creating
 Network dolibarr-24.0.2-stack_default Created
 Container dolibarr-2402-mariadb Creating
 Container dolibarr-2402-mariadb Created
 Container dolibarr-2402-mariadb Starting
 Container dolibarr-2402-mariadb Started
 Container dolibarr-2402-mariadb Waiting
 Container dolibarr-2402-mariadb Healthy
 Container dolibarr-2402-web Starting
 Container dolibarr-2402-web Started

等待约 30 秒后复查服务与数据：

docker compose ps
docker compose exec mariadb mariadb -udolidbuser -pdolidbpass dolibarr \
  -e "SELECT COUNT(*) AS tables_after_restart FROM information_schema.tables WHERE table_schema='dolibarr';"
curl -s http://127.0.0.1:8147/ | grep -oE '<title>[^<]*</title>'

实测输出：

NAME                    IMAGE                      COMMAND                   SERVICE   CREATED          STATUS                    PORTS
dolibarr-2402-mariadb   mariadb:10.11              "docker-entrypoint.s…"   mariadb   36 seconds ago   Up 35 seconds (healthy)   3306/tcp
dolibarr-2402-web       dolibarr/dolibarr:24.0.2   "docker-run.sh apach…"   web       36 seconds ago   Up 25 seconds             0.0.0.0:8147->80/tcp, [::]:8147->80/tcp
tables_after_restart
410
<title>Login @ 24.0.2</title>

同时启动日志会走「已安装」分支，不再重新建表：

dolibarr-2402-web  | Current Version of files is : 24.0.2
dolibarr-2402-web  | DOLI_INSTALL_AUTO is on, so we check to initialize or upgrade mariadb database
dolibarr-2402-web  | DB Exists is : dolibarr
dolibarr-2402-web  | Install.lock Exists is : yes

结论：down/up 全程删掉的是容器与网络，三个 bind mount 目录不动，库表数据（410 张表）、管理员账号、install.lock 全部原样保留，应用直接进入登录态。

💡 说明：数据都在宿主机目录，日常备份只需两步——mariadb-dump 导出数据库（见"十、常用运维命令"）+ tar 打包 data/documents/（上传文档与生成文件）。

六、环境变量表

以下为 Web 服务（dolibarr/dolibarr:24.0.2）支持的常用环境变量，实测取自启动脚本 docker-run.sh 与容器内运行时环境（docker compose exec web env），「本文实测值」列即 4.2 编排文件中的取值：

环境变量作用默认值本文实测值
DOLI_DB_HOST数据库主机mysql（建议改为服务名）mariadb
DOLI_DB_HOST_PORT数据库端口33063306
DOLI_DB_NAME数据库名dolibarrdolibarr
DOLI_DB_USER数据库账号dolibarrdolidbuser
DOLI_DB_PASSWORD数据库密码dolibarrpassdolidbpass
DOLI_DB_TYPE数据库驱动mysqlimysqli（可选 pgsql）
DOLI_DB_SSL是否启用 DB SSLfalsefalse
DOLI_URL_ROOT对外访问根地址http://localhosthttp://192.168.146.128:8147
DOLI_ADMIN_LOGIN自动创建的管理员登录名adminadmin
DOLI_ADMIN_PASSWORD管理员密码adminq1w2e3r4
DOLI_INSTALL_AUTO首次启动自动安装数据库11
DOLI_PROD生产模式标志（写入 conf.php）01
DOLI_AUTH认证方式dolibarrdolibarr（可选 ldap、http、forceuser 等）
DOLI_CRON容器内启 Dolibarr 计划任务（每 5 分钟跑一次 cron_run_jobs.php）00
DOLI_CRON_KEY计划任务密钥（DOLI_CRON=1 时注入 llx_const 的 CRON_KEY）空未设置
DOLI_CRON_USER计划任务执行身份用户空未设置
DOLI_VERSION镜像声明的应用版本（只读参考，勿改）随镜像24.0.2
PHP_INI_DATE_TIMEZONEPHP 时区UTCAsia/Shanghai
PHP_INI_MEMORY_LIMITPHP memory_limit256M512M
PHP_INI_UPLOAD_MAX_FILESIZE单文件上传上限100M50M
PHP_INI_POST_MAX_SIZEPOST 包体上限100M55M
PHP_INI_ALLOW_URL_FOPENallow_url_fopen00

MariaDB 服务侧（mariadb:10.11 官方镜像）：

环境变量作用本文实测值
MARIADB_ROOT_PASSWORDroot 密码（首次初始化生效）q1w2e3r4
MARIADB_DATABASE自动创建的库dolibarr
MARIADB_USER自动创建的业务账号dolidbuser
MARIADB_PASSWORD业务账号密码dolidbpass

⚠️ 注意：MARIADB_* 只在数据目录为空（首次初始化）时生效；data/mariadb 已有数据后改这些变量不会改库内账号密码。管理员账号密码同理，DOLI_ADMIN_* 只在 DOLI_INSTALL_AUTO 首次安装时写入。

计划任务说明：DOLI_CRON=1 时启动脚本会写入 /etc/cron.d/dolibarr，内容为每 5 分钟以 www-data 身份执行一次 /var/www/scripts/cron/cron_run_jobs.php <DOLI_CRON_KEY> <DOLI_CRON_USER>，替代在系统里手工部署 cron。

七、配置参数说明

容器形态下 Dolibarr 的配置分三层，改动优先级从高到低：

  1. compose 环境变量（DOLI_*、PHP_INI_*）：启动脚本每次启动都会据此重新生成 /var/www/html/conf/conf.php 与 /usr/local/etc/php/conf.d/dolibarr-php.ini，这是容器形态下唯一持久的配置入口；
  2. conf.php（/var/www/html/conf/conf.php）：应用层配置文件，默认由环境变量托管生成（实测内容见 4.5 第三步）；
  3. 数据库配置（llx_const 表）：界面「设置 → 系统 → 常规配置」写入的运行参数（语言、上传上限、公司名等），随数据库持久化。

实测证据——启动日志每次都会重算配置（第二次启动同样出现）：

dolibarr-2402-web  | [INIT] => update PHP Config ...
dolibarr-2402-web  | [INIT] => update Dolibarr Config ...

⚠️ 注意：不要直接改容器内的 conf.php——它不在挂载卷里，且每次启动都被环境变量重写，手工改动会丢。要改配置一律改 compose 的 environment: 再 docker compose up -d 重建服务。例如把内存上限调到 1G：改 PHP_INI_MEMORY_LIMIT: 1024M 后 docker compose up -d web 即可。

conf.php 关键生成项对照（右侧为对应的 compose 环境变量）：

conf.php 键生成来源说明
$dolibarr_main_url_rootDOLI_URL_ROOT对外访问地址，邮件里的链接也用它
$dolibarr_main_document_root固定 /var/www/html程序根，镜像内固定
$dolibarr_main_data_root固定 /var/www/documents数据根，对应挂载 ./data/documents
$dolibarr_main_db_hostDOLI_DB_HOST数据库主机
$dolibarr_main_db_portDOLI_DB_HOST_PORT数据库端口
$dolibarr_main_db_user / $dolibarr_main_db_passDOLI_DB_USER / DOLI_DB_PASSWORD连库凭据
$dolibarr_main_db_typeDOLI_DB_TYPEmysqli / pgsql
$dolibarr_main_prodDOLI_PROD1 为生产模式
$dolibarr_main_instance_unique_id自动生成实例唯一密钥，用于会话与加密场景
$dolibarr_main_db_character_set / $dolibarr_main_db_collation固定utf8mb4 / utf8mb4_unicode_ci

conf.php 全部可用键（含容器场景较少用到的安全键）的逐项详解，见本站 C1 篇：《Dolibarr 24.0 配置参数详解》。

八、配置文件挂载

三个挂载点各自承载什么、怎么用：

挂载容器内路径用途实测行为
./data/mariadb/var/lib/mysql数据库文件首次启动自动初始化系统库 + dolibarr 库；down/up 后数据完整（见第五章实测）
./data/documents/var/www/documentsDolibarr 数据根生成 install.lock、initdb.log、users/ 上传目录；后续所有上传文档、生成的 PDF/备份都落这里
./data/custom/var/www/html/custom外部模块目录默认空；把第三方模块解压到此处即可被应用加载（对应 conf.php 的 $dolibarr_main_document_root_alt）

目录属主说明：documents/ 必须可被容器内 Web 运行用户（www-data，uid 33）写入。首次启动让 Docker 自动创建宿主目录时属主就是 www-data（见第五章 ls 实测输出）；如果手工预建了目录，执行：

sudo chown -R 33:33 /opt/dolibarr/data/documents

PHP 配置覆盖：不需要挂载 php.ini，用 PHP_INI_* 环境变量即可（生成文件见 4.5 第三步实测）。需要额外 PHP 指令时，可挂载自定义 ini 到 /usr/local/etc/php/conf.d/，但注意启动脚本生成的 dolibarr-php.ini 排在其后加载、同名指令以它为准。

九、等价 docker run

不用 compose 时，以下两条 docker run 与本文编排完全等价（先建网络，再按依赖顺序启动）：

docker network create dolibarr-24.0.2-stack_default

docker run -d --name dolibarr-2402-mariadb \
  --network dolibarr-24.0.2-stack_default \
  -e MARIADB_ROOT_PASSWORD=q1w2e3r4 \
  -e MARIADB_DATABASE=dolibarr \
  -e MARIADB_USER=dolidbuser \
  -e MARIADB_PASSWORD=dolidbpass \
  -v /opt/dolibarr/data/mariadb:/var/lib/mysql \
  --restart unless-stopped \
  mariadb:10.11

等数据库初始化完成（约 20 秒，docker logs dolibarr-2402-mariadb 出现 ready for connections）后启动应用：

docker run -d --name dolibarr-2402-web \
  --network dolibarr-24.0.2-stack_default \
  -p 8147:80 \
  -e DOLI_DB_HOST=mariadb \
  -e DOLI_DB_HOST_PORT=3306 \
  -e DOLI_DB_NAME=dolibarr \
  -e DOLI_DB_USER=dolidbuser \
  -e DOLI_DB_PASSWORD=dolidbpass \
  -e DOLI_URL_ROOT=http://192.168.146.128:8147 \
  -e DOLI_ADMIN_LOGIN=admin \
  -e DOLI_ADMIN_PASSWORD=q1w2e3r4 \
  -e DOLI_INSTALL_AUTO=1 \
  -e DOLI_PROD=1 \
  -e PHP_INI_DATE_TIMEZONE=Asia/Shanghai \
  -e PHP_INI_MEMORY_LIMIT=512M \
  -e PHP_INI_UPLOAD_MAX_FILESIZE=50M \
  -e PHP_INI_POST_MAX_SIZE=55M \
  -v /opt/dolibarr/data/documents:/var/www/documents \
  -v /opt/dolibarr/data/custom:/var/www/html/custom \
  --restart unless-stopped \
  dolibarr/dolibarr:24.0.2

💡 说明：compose 版的优势正在于省掉手工等待——depends_on + condition: service_healthy 自动完成"数据库健康后才启动应用"的编排；docker run 方式只能人工等待或靠脚本探测。生产建议用 compose。

十、常用运维命令

以下命令均在 /opt/dolibarr 目录下执行（compose 会自动识别 docker-compose.yml 与项目名 dolibarr-24.0.2-stack）。

服务状态与日志：

docker compose ps                  # 两服务状态（期望 mariadb healthy）
docker compose logs -f web         # 跟踪应用日志（Ctrl+C 退出）
docker compose logs --tail 50 web  # 最近 50 行

启停：

docker compose restart web         # 只重启应用
docker compose stop                # 全部停止（保留容器）
docker compose start               # 恢复启动
docker compose down                # 删除容器与网络（bind mount 数据保留，实测见第五章）

数据库备份（实测）：

docker compose exec mariadb sh -c 'mariadb-dump -udolidbuser -pdolidbpass dolibarr' > /opt/dolibarr/backup-$(date +%F).sql

备份文件头部实测内容：

/*M!999999\- enable the sandbox mode */
-- MariaDB dump 10.19  Distrib 10.11.19-MariaDB, for debian-linux-gnu (x86_64)
--
-- Host: localhost    Database: dolibarr
-- ------------------------------------------------------
-- Server version       10.11.19-MariaDB-ubu2204

/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;

恢复（目标库为空时）：

docker compose exec -T mariadb sh -c 'mariadb -udolidbuser -pdolidbpass dolibarr' < /opt/dolibarr/backup-2026-10-23.sql

文档目录备份与恢复（上传文件、生成文档）：

tar -czf /opt/dolibarr/documents-$(date +%F).tar.gz -C /opt/dolibarr/data documents

版本升级（锁定版本号升级法）：

# 1) 先备份（上一条的 mariadb-dump + documents tar）
# 2) 修改 docker-compose.yml 中两处镜像 tag（如 24.0.2 -> 下一个补丁版）
# 3) 拉新镜像并重建
docker compose pull
docker compose up -d

⚠️ 注意：升级后首次启动，DOLI_INSTALL_AUTO=1 的启动脚本会检测 MAIN_VERSION_LAST_INSTALL 常量与文件版本差异并自动执行升级迁移（日志出现 we launch upgrade 字样）。跨大版本（如 23.x → 24.0）务必先查官方 Upgrade 文档确认迁移路径，并保留可回滚的备份。

镜像更新检查：

docker compose pull

实测输出（无新版本时）：

 Image mariadb:10.11 Pulling
 Image dolibarr/dolibarr:24.0.2 Pulling
 Image mariadb:10.11 Pulled
 Image dolibarr/dolibarr:24.0.2 Pulled

进入容器排查：

docker compose exec web bash       # 应用服务（Debian 环境）
docker compose exec mariadb mariadb -udolidbuser -pdolidbpass dolibarr

十一、常见问题

Q1：启动日志有 AH00558: apache2: Could not reliably determine the server's fully qualified domain name，要处理吗？ 实测日志原文：

AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 10.0.1.3. Set the 'ServerName' directive globally to suppress this message

无害，Apache 只是在提示未设全局 ServerName、用内网 IP 兜底，服务照常监听（实测 curl 返回 200）。强迫症可在编排里给 web 服务加 environment: APACHE_SERVER_NAME=dolibarr.local？——该镜像未暴露此变量，正确做法是挂一个自定义 apache2 conf 到 /etc/apache2/conf-available/ 写 ServerName localhost，或者直接忽略。

Q2：日志里 mkdir: cannot create directory '/var/www/html/conf': File exists 是报错吗？ 不是。启动脚本先探测后创建，conf 目录由镜像自带（见第四章日志上下文，紧随其后的 [INIT] => update Dolibarr Config 都正常完成），幂等脚本必然输出这一行，可忽略。

Q3：访问页面报数据库连接失败/未安装怎么办？ 按顺序排查：docker compose ps 看 mariadb 是否 healthy——不健康说明数据库没就绪，docker compose logs mariadb 看初始化报错（常见是 data/mariadb 目录残留了旧实例的库文件但密码对不上）；healthy 而应用仍连不上，核对 compose 里 DOLI_DB_USER/DOLI_DB_PASSWORD 与 MARIADB_USER/MARIADB_PASSWORD 是否一致，且数据目录不是"已初始化过的旧库"（旧库的账号密码以首次初始化时为准）。

Q4：手工改了容器内 conf.php，重启后又变回去了？ 正常现象。启动脚本每次启动都按 DOLI_* 环境变量重新生成 conf.php（实测每次启动日志都有 [INIT] => update Dolibarr Config）。容器形态下改配置的唯一持久入口是 compose 的 environment:，改完 docker compose up -d 重建生效（原理见第七章）。

Q5：登录后跳转到错误地址/邮件里的链接打不开？ DOLI_URL_ROOT 与实际访问地址不一致所致。该值被写进 conf.php 的 $dolibarr_main_url_root（见 4.5 实测），是全站链接的基准。改成用户浏览器真实访问的 http://<IP或域名>:<端口> 后重建服务。

Q6：上传附件超过 2MB 失败？ 两处上限，取交集：一是 PHP 层 upload_max_filesize（本文已调到 50M，实测 dolibarr-php.ini 生效值）；二是 Dolibarr 数据库配置 MAIN_UPLOAD_DOC（单位 KB，实测默认值 2048 即 2MB），在管理界面「设置 → 系统 → 常规配置」里调大，或直接改库：

docker compose exec mariadb mariadb -udolidbuser -pdolidbpass dolibarr \
  -e "UPDATE llx_const SET value='51200' WHERE name='MAIN_UPLOAD_DOC';"

Q7：想启用 Dolibarr 自带的定时任务（自动发邮件、提醒等）？ 在 web 服务环境变量加 DOLI_CRON: 1，并设置 DOLI_CRON_KEY（任意随机串）与 DOLI_CRON_USER: admin，重建后容器内每 5 分钟自动跑一次计划任务脚本；CRON_KEY 常量会被同步写入数据库。也可以不用容器内 cron，在宿主机 crontab 里手动调度（CLI 用法见本站 D1 篇 《Dolibarr 24.0 常用 CLI 命令与工具详解》）。

Q8：数据想换到更大的磁盘？ 停服务（docker compose down），把 /opt/dolibarr/data/ 整体迁移到新磁盘路径，修改 compose 里三处 volumes 的宿主路径，再 docker compose up -d。数据库文件、文档、模块目录随挂载一起搬家，无需改库。

十二、参考链接