Ubuntu 22.04 安装 Dolibarr 24.0 指南
Ubuntu 22.04 服务器以官方 tar.gz + LAMP 依赖链从 0 到 1 安装 Dolibarr 24.0.2 的全流程实测：下载校验、建库授权、Apache 站点、五步安装向导、install.lock 收尾、排障实录与升级卸载。
Ubuntu 22.04 安装 Dolibarr 24.0 指南
目标：在一台 Ubuntu 22.04 服务器上，使用官方 tar.gz 包 + LAMP（Apache + MariaDB + PHP）依赖链，从零完成 Dolibarr ERP/CRM 24.0.2 的安装、初始化、管理员账号创建与生产收尾，并覆盖排障实录、升级与卸载。本文全部命令与回显均在 Ubuntu 22.04.5 LTS 实测服务器上真实执行并逐行照抄，Dolibarr 版本为 24.0.2（本地安装包 24.0.2，SHA-256 已核验）。
一、环境信息
本次实测环境与关键路径如下，全文命令均以此环境为基准：
- 操作系统：Ubuntu 22.04.5 LTS（
PRETTY_NAME="Ubuntu 22.04.5 LTS"，x86_64） - Web 服务：Apache 2.4.52（
apache2 2.4.52-1ubuntu4.25，模块php_module (shared)） - PHP：8.1.2-1ubuntu2.28（Ubuntu 22.04 官方源默认版本，
libapache2-mod-php8.1 8.1.2-1ubuntu2.28） - 数据库：MariaDB 10.6.23（
1:10.6.23-0ubuntu0.22.04.1，mariadb Ver 15.1 Distrib 10.6.23-MariaDB） - 应用软件：Dolibarr ERP & CRM 24.0.2（官方 GitHub 发布源码包
dolibarr-24.0.2.tar.gz，83,798,213 字节） - 安装目录：
/var/www/dolibarr（htdocs为程序根，documents为数据根） - 数据库名/前缀：
dolibarr/llx_（安装向导默认） - 站点端口：80（演示用
http://localhost，生产请替换为服务器域名或 IP） - 演示账号：Dolibarr 管理员
admin/q1w2e3r4；数据库业务账号dolibarr/q1w2e3r4
💡 说明：Dolibarr 的安装分「代码部署」与「数据库初始化」两段，数据库初始化由其自带 Web 安装向导完成（本篇第四章），因此 MariaDB/MySQL 是硬依赖——请勿在未准备好数据库的情况下开始安装向导。
二、前置条件
2.1 硬件与系统要求
Dolibarr 是典型的 LAMP 单体 Web 应用，对硬件要求不高。官方 Wiki《Prerequisites》页给出的最低要求为 Apache/Nginx + PHP + MySQL/MariaDB/PostgreSQL；结合实测，建议如下：
| 项目 | 最低 | 建议（10 人以下团队日常使用） |
|---|---|---|
| CPU | 1 核 | 2 核 |
| 内存 | 1 GB | 4 GB（PHP memory_limit 256M 起） |
| 磁盘 | 2 GB | 20 GB（含上传文档与数据库增长） |
| 系统 | Ubuntu 20.04/22.04/24.04 均可 | Ubuntu 22.04 LTS |
关键差异：内存低于 1 GB 时安装向导能跑完，但启用报表、文档生成后容易触发 PHP 内存耗尽；生产建议按 4 GB 起步。
2.2 软件依赖链（LAMP）与 PHP 扩展清单
Dolibarr 24.0 运行所需的 PHP 扩展，以其自带环境自检页（/install/check.php）的判定为准。实测环境安装依赖后，自检通过项包括：Calendar、Xml、Dom、UTF8、Intl、IMAP、ZIP 等函数支持与 mysqli 数据库驱动。因此 apt 安装清单如下：
| 软件包 | 作用 | 是否必需 |
|---|---|---|
| apache2 | Web 服务（mod_php 模式） | 必需 |
| libapache2-mod-php | Apache 的 PHP SAPI（漏装会导致源码直出，见第九章 FAQ） | 必需 |
| php-cli | PHP 命令行（安装排障与 CLI 脚本） | 必需 |
| php-mysql | mysqli 驱动（连接 MariaDB/MySQL） | 必需 |
| php-gd | 图片验证码、缩略图 | 必需 |
| php-xml | SimpleXML/XML 解析 | 必需 |
| php-mbstring | 多字节字符串 | 必需 |
| php-curl | 外部接口调用（在线市场、Webhook 等） | 必需 |
| php-zip | 压缩/解压、备份导出 | 必需 |
| php-intl | 国际化（installer 自检项） | 必需 |
| php-imap | 邮件抓取模块（PHP ≤ 8.3 时自检项） | 建议 |
| php-ldap | LDAP 对接模块（用不到 LDAP 可不装） | 可选 |
| mariadb-server / mariadb-client | 数据库服务与客户端 | 必需 |
💡 技术拓展：Web 服务与 PHP 的组合不止「Apache + mod_php」一种。常见组合对比——
组合 特点 适用场景 Apache + mod_php 每个请求常驻 PHP 解释器，配置简单， .htaccess生效单机标准部署（本文采用） Nginx + PHP-FPM 进程池管理 PHP，内存占用低、并发能力强 高并发、多站点共享 Apache + PHP-FPM（proxy_fcgi） Apache 兼容性与 FPM 性能兼得 已有 Apache 体系的性能优化 Dolibarr 官方对三者均支持；本文因 Ubuntu 22.04 的
apt一条命令即可装齐且.htaccess开箱生效，采用「Apache + mod_php」。
2.3 端口与网络规划
- 80/tcp（或自定端口）：HTTP 站点，浏览器访问 Dolibarr 与安装向导；
- 3306/tcp：MariaDB。本机安装（
db_host=localhost）时无需对外放通，建议仅监听127.0.0.1； - 安装期间需保证服务器能访问 GitHub（下载安装包）。若网络受限，可在国内镜像或离线机器下载
dolibarr-24.0.2.tar.gz后以scp上传，后续步骤完全一致。
三、版本选型说明
选版本前先确认「从哪里拿包」。以下渠道均在本次实测中逐一验证（取证日期 2026-10-23）：
| 分发渠道 | 实测命令/现象 | 结论 |
|---|---|---|
| GitHub Releases「Source code (tar.gz)」 | wget https://github.com/Dolibarr/dolibarr/archive/refs/tags/24.0.2.tar.gz → 200 OK，83,798,213 字节，SHA-256 e1082162c635911be9e773891eea140d84d51e682300cb2f35ca43178146cedc | ✅ 推荐主线 |
| GitHub Releases「Source code (zip)」 | wget https://github.com/Dolibarr/dolibarr/archive/refs/tags/24.0.2.zip → 93,802,182 字节，unzip -l 结构与 tar.gz 相同 | ✅ 备用（第五章） |
旧官方分发包站 dl.dolibarr.org | wget https://dl.dolibarr.org/dolibarr-24.0.2.zip → failed: No address associated with hostname（域名已无法解析） | ❌ 不可用 |
| Ubuntu 22.04 软件源 apt | apt-cache policy dolibarr → 无任何输出（jammy 仓库不收录 dolibarr 包） | ❌ 不可用 |
应用编排方案（官方 dolibarr/dolibarr 应用与数据库同栈） | 官方提供 24.0.2 应用包与编排文件，一键初始化 | ➡️ 另见本站《Dolibarr Docker Compose 部署指南》 |
关于版本号：24.0 线的节奏为大版本 8 月落地（24.0.0），其后约每 4~6 周一个补丁版（24.0.1、24.0.2…）。截至本文实测日，最新稳定补丁版为 24.0.2，本文按 24.0.2 全流程实测。补丁版之间不含数据库结构变更，升级成本低（见第八章）。
💡 说明：Dolibarr 24.0 对 PHP 的最低版本要求为 8.1（Ubuntu 22.04 官方源恰为 PHP 8.1，开箱即满足）；安装器自检页在 PHP 低于 8.3 时仅提示可安装 IMAP 扩展，不阻断安装。
四、方案 A：官方 tar.gz + LAMP 手动安装（主线）
4.1 方案说明
本方案是 Dolibarr 官方推荐的标准安装路径：系统源安装 LAMP 依赖链 → 下载官方 tar.gz 源码包 → 解压到 /var/www/dolibarr → 手工建库授权 → 配置 Apache 虚拟主机 → 浏览器进入自带安装向导完成数据库初始化与管理员创建 → 落 install.lock 收尾。全程无需 composer 等构建步骤，tar.gz 内已包含全部程序文件。
4.2 安装 LAMP 依赖链
先更新软件源索引，再一次性安装 Apache、MariaDB 与 PHP 全套扩展：
apt-get update
实测输出（节选末尾）：
Get:7 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [4430 kB]
Get:8 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 Packages [1628 kB]
Fetched 12.5 MB in 4s (3004 kB/s)
Reading package lists...
DEBIAN_FRONTEND=noninteractive apt-get install -y \
apache2 mariadb-server mariadb-client \
php-cli php-gd php-xml php-mbstring php-curl php-zip php-intl php-mysql php-imap php-ldap \
libapache2-mod-php wget curl
实测输出（节选，完整日志较长）：
Setting up libapache2-mod-php8.1 (8.1.2-1ubuntu2.28) ...
Setting up libapache2-mod-php (2:8.1+92ubuntu1) ...
Setting up mariadb-server (1:10.6.23-0ubuntu0.22.04.1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
Processing triggers for php8.1-cli (8.1.2-1ubuntu2.28) ...
启动并设置开机自启（两个服务逐个执行，便于分别核对状态）：
systemctl enable --now mariadb
实测输出：
Executing: /lib/systemd/systemd-sysv-install enable mariadb
systemctl enable --now apache2
实测输出：
Executing: /lib/systemd/systemd-sysv-install enable apache2
验证三个核心组件版本与运行状态：
systemctl is-active mariadb apache2
实测输出：
active
active
apache2 -v && php -v | head -1 && mariadb --version
实测输出：
Server version: Apache/2.4.52 (Ubuntu)
Server built: 2026-10-08T19:59:46
PHP 8.1.2-1ubuntu2.28 (cli) (built: Oct 19 2026 18:54:45) (NTS)
mariadb Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using EditLine wrapper
核对关键 PHP 扩展是否就位（安装器自检依据）：
php -m | grep -E "^(mysqli|gd|curl|mbstring|xml|zip|intl|imap|ldap|dom|session)$" | tr "\n" " "
实测输出：
curl dom gd imap intl ldap mbstring mysqli session xml zip
⚠️ 注意：php-cli 只提供命令行 PHP，必须单独安装 libapache2-mod-php，否则 Apache 会把 PHP 文件当纯文本源码输出（实测踩坑，见第九章 FAQ 第一条）。
4.3 下载官方 tar.gz 并校验
cd /root
wget --progress=dot:giga https://github.com/Dolibarr/dolibarr/archive/refs/tags/24.0.2.tar.gz
实测输出：
Connecting to codeload.github.com (codeload.github.com)|20.205.243.165|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 83798213 (80M) [application/x-gzip]
Saving to: '24.0.2.tar.gz'
0K ........ ........ ........ ........ 40% 10.2M 5s
32768K ........ ........ ........ ........ 80% 18.3M 1s
65536K ........ ....... 100% 17.2M=5.8s
'24.0.2.tar.gz' saved
校验 SHA-256 并核对文件大小：
sha256sum 24.0.2.tar.gz && ls -l 24.0.2.tar.gz
实测输出：
e1082162c635911be9e773891eea140d84d51e682300cb2f35ca43178146cedc 24.0.2.tar.gz
-rw-r--r-- 1 root root 83798213 Oct 22 21:13 24.0.2.tar.gz
💡 说明：GitHub 对同一 tag 的源码归档是确定性生成的，同一版本号在任何时间下载的 SHA-256 一致；若你的校验值与上不符，优先怀疑下载中断或代理篡改，删除重下。
4.4 解压部署到 /var/www/dolibarr
先看包内结构再落位：
tar tzf 24.0.2.tar.gz | head -5
实测输出：
dolibarr-24.0.2/
dolibarr-24.0.2/.agents/
dolibarr-24.0.2/.agents/AGENTS.md
dolibarr-24.0.2/.agents/agents/
dolibarr-24.0.2/.agents/skills/
解压并移动到部署目录，同时创建数据目录 documents（GitHub 源码包中不含该目录，需手工创建）：
tar xzf 24.0.2.tar.gz
mv dolibarr-24.0.2 /var/www/dolibarr
mkdir -p /var/www/dolibarr/documents
按最小权限原则授权：documents（上传/生成的文档与备份）与 htdocs/conf（安装器要写入 conf.php）归 Web 运行用户 www-data，其余程序文件保持 root 属主只读：
chown -R www-data:www-data /var/www/dolibarr/documents /var/www/dolibarr/htdocs/conf
ls -ld /var/www/dolibarr /var/www/dolibarr/documents /var/www/dolibarr/htdocs/conf
实测输出：
drwxrwxr-x 6 root root 4096 Oct 22 21:13 /var/www/dolibarr
drwxr-xr-x 2 www-data www-data 4096 Oct 22 21:13 /var/www/dolibarr/documents
drwxrwxr-x 2 www-data www-data 4096 Oct 2 12:03 /var/www/dolibarr/htdocs/conf
确认程序根目录结构：
ls /var/www/dolibarr
实测输出：
COPYING COPYRIGHT ChangeLog DCO README.md SECURITY.md composer.json.disabled
htdocs phpstan.neon.dist pyproject.toml robots.txt scripts
关键差异解读：htdocs 是 Web 站点根（全部 PHP 入口），scripts 是 CLI 脚本库（详见本站 D1 篇），documents 是运行期生成的数据根——升级时只替换前两者、绝不覆盖 documents。
4.5 创建数据库与业务账号
MariaDB 为 Dolibarr 建库、建号并授权（演示密码 q1w2e3r4，生产请更换）：
mariadb -uroot -e "CREATE DATABASE dolibarr CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mariadb -uroot -e "CREATE USER 'dolibarr'@'localhost' IDENTIFIED BY 'q1w2e3r4';"
mariadb -uroot -e "GRANT ALL PRIVILEGES ON dolibarr.* TO 'dolibarr'@'localhost'; FLUSH PRIVILEGES;"
验证库与账号均已就位：
mariadb -uroot -e "SHOW DATABASES; SELECT User,Host FROM mysql.user WHERE User='dolibarr';"
实测输出：
Database
dolibarr
information_schema
mysql
performance_schema
sys
User Host
dolibarr localhost
💡 说明：建库语句显式指定
utf8mb4/utf8mb4_unicode_ci，库默认字符集为 utf8mb4；而 Dolibarr 24.0 的安装器在生成表时固定使用 utf8（源码中为规避 utf8mb4 的索引长度限制刻意回退，见第九章 FAQ），两者并存不影响使用。
4.6 配置 Apache 虚拟主机
写入站点配置（ServerName 换成你的域名或服务器 IP）：
cat > /etc/apache2/sites-available/dolibarr.conf <<'EOF'
<VirtualHost *:80>
ServerName dolibarr.example.com
DocumentRoot /var/www/dolibarr/htdocs
<Directory /var/www/dolibarr/htdocs>
Options -Indexes +FollowSymLinks
AllowOverride All
Require all granted
</Directory>
<Directory /var/www/dolibarr/documents>
Require all denied
</Directory>
ErrorLog ${APACHE_LOG_DIR}/dolibarr_error.log
CustomLog ${APACHE_LOG_DIR}/dolibarr_access.log combined
</VirtualHost>
EOF
配置要点逐项说明：
DocumentRoot /var/www/dolibarr/htdocs：站点根必须指向htdocs子目录，而不是/var/www/dolibarr，否则程序文件会暴露；Options -Indexes：禁止目录列表，防止文档/脚本目录被浏览；AllowOverride All：允许htdocs内.htaccess生效（Dolibarr 对部分目录有访问控制规则）；documents目录Require all denied：上传文档是敏感数据，绝不能通过 Web 直接访问，只能由 Dolibarr 程序内部读取；- 独立的
dolibarr_error.log/dolibarr_access.log：排障时不与其他站点日志混杂。
启用站点、停用默认站点并重载：
a2dissite 000-default
实测输出：
Site 000-default disabled.
To activate the new configuration, you need to run:
systemctl reload apache2
a2ensite dolibarr
实测输出：
Enabling site dolibarr.
To activate the new configuration, you need to run:
systemctl reload apache2
apache2ctl configtest
实测输出（AH00558 是未配置全局 ServerName 的常规提示，不影响运行）：
AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 10.0.0.6. Set the 'ServerName' directive globally to suppress this message
Syntax OK
systemctl reload apache2
验证：此时 conf.php 尚未生成，访问根路径会被 Dolibarr 重定向到安装向导：
curl -sI http://localhost/
实测输出：
HTTP/1.1 302 Found
Date: Thu, 22 Oct 2026 21:13:51 GMT
Server: Apache/2.4.52 (Ubuntu)
Location: install/index.php
4.7 Web 安装向导（五步完成初始化）
Dolibarr 自带图形化安装向导，共 5 个步骤：语言选择 → 环境自检 → 配置文件生成（step1）→ 数据库对象创建（step2）→ 管理员账号创建（step4）→ 完成收尾（step5）。以下逐步给出访问入口、需要填写的内容与真实页面回显。
第一步：浏览器打开 http://<服务器地址>/install/（演示环境为 http://localhost/install/）。页面显示「24.0.2 Dolibarr install or upgrade」，检测到配置文件不存在并要求选择语言：
24.0.2 Dolibarr install or upgrade
The configuration file conf/conf.php does not exists or is not readable.
We will run the installation process to try to initialize it.
Default language : Autodetect Albanian Arabic (Algeria) Arabic (Egypt) Chinese
English (Australia) ... (语言清单共 80 余项，此处省略中段) ... Ukrainian Urdu
Uzbek Vietnamese Welsh
选择语言（如 English 或 Chinese）后进入环境自检页 check.php，全部通过后点击「Start」。
第二步：配置文件页 fileconf.php。⚠️ 首次安装必须预先创建空的 conf.php 并授权，否则向导报错（实测踩坑）：
touch /var/www/dolibarr/htdocs/conf/conf.php
chown www-data:www-data /var/www/dolibarr/htdocs/conf/conf.php
未创建时直接提交 step1 的实测报错回显：
Configuration file htdocs/conf/conf.php is not writable. Check permissions.
For first install, your web server must be able to write into this file during
configuration process ("chmod 666" for example on a Unix like OS).
创建后，在表单中按下表填写：
| 表单字段 | 填写值 | 说明 |
|---|---|---|
| Web server directory（main_dir） | /var/www/dolibarr/htdocs | 程序根绝对路径 |
| Documents directory（main_data_dir） | /var/www/dolibarr/documents | 数据根绝对路径 |
| Dolibarr root URL（main_url） | http://localhost | 生产填域名/IP，不含结尾 / |
| Database type（db_type） | mysqli | MariaDB/MySQL 选 mysqli |
| Database server（db_host） | localhost | 本机库；远程库填主机名 |
| Database name（db_name） | dolibarr | 4.5 节创建的库名 |
| Login（db_user）/ Password | dolibarr / q1w2e3r4 | 4.5 节创建的业务账号 |
| Port（db_port） | 3306 | MariaDB 默认端口 |
| Tables prefix（db_prefix） | llx_ | 官方默认前缀 |
| Create database / Create user | 不勾选 | 库与账号已手工建好；未预建时可勾选并提供 root 凭据 |
提交后进入 step1（生成配置文件），实测回显：
24.0.2 Dolibarr install or upgrade - Configuration file
Configuration file
Saving parameters to ../conf/conf.php
Reloading parameters from configuration file.
Server connection (User dolibarr) : localhost
Database connection (User dolibarr) : dolibarr
生成的 /var/www/dolibarr/htdocs/conf/conf.php 实测内容（去掉空行与注释）：
<?php
$dolibarr_main_url_root='http://localhost';
$dolibarr_main_document_root="/var/www/dolibarr/htdocs";
$dolibarr_main_url_root_alt='/custom';
$dolibarr_main_document_root_alt="/var/www/dolibarr/htdocs/custom";
$dolibarr_main_data_root="/var/www/dolibarr/documents";
$dolibarr_main_db_host='localhost';
$dolibarr_main_db_port='3306';
$dolibarr_main_db_name='dolibarr';
$dolibarr_main_db_prefix='llx_';
$dolibarr_main_db_user='dolibarr';
$dolibarr_main_db_pass='q1w2e3r4';
$dolibarr_main_db_type='mysqli';
$dolibarr_main_db_character_set='utf8';
$dolibarr_main_db_collation='utf8_unicode_ci';
$dolibarr_main_authentication='dolibarr';
$dolibarr_main_prod='0';
$dolibarr_main_force_https='0';
$dolibarr_main_restrict_os_commands='mariadb-dump, mariadb, mysqldump, mysql, pg_dump, pg_restore, clamdscan, clamdscan.exe, ls, tar, gzip, bzip2, zstd';
$dolibarr_main_restrict_eval_methods='getDolGlobalString, getDolGlobalInt, getDolCurrency, getDolEntity, getDolDBType, fetchNoCompute, hasRight, isAdmin, isModEnabled, isStringVarMatching, dolSort, abs, min, max, round, dol_now, preg_match';
$dolibarr_nocsrfcheck='0';
$dolibarr_main_instance_unique_id='168df7e37e8c202847d11636b25476b40f4b500779479ce598d8321dd38273ed';
$dolibarr_mailing_limit_sendbyweb='0';
$dolibarr_mailing_limit_sendbycli='0';
$dolibarr_main_distrib='standard';
💡 说明：该文件由安装器自动生成，逐项含义与调优见本站《Dolibarr 24.0 配置参数详解》。其中
$dolibarr_main_prod='0'表示「非生产模式」，收尾阶段建议改为1（见 4.8 节）。
第三步：数据库对象创建（step2）。点击「Start」后安装器连接库、建表、导入字典数据。实测回显：
24.0.2 Dolibarr install or upgrade - Database objects creation
Database Server connection : localhost
Database version 5.5.5-10.6.23-MariaDB-0ubuntu0.22.04.1
Database name dolibarr
Tables and Primary keys creation
Foreign keys and indexes creation
Functions creation
Reference data loading
Make an anonymous Ping '+1' to the Dolibarr foundation server
(done 1 time only after installation) to allow the foundation to
count the number of Dolibarr installation.
建表完成，用 SQL 核对表数量：
mariadb -udolibarr -pq1w2e3r4 dolibarr \
-e "SELECT COUNT(*) AS tables_created FROM information_schema.tables WHERE table_schema='dolibarr';"
实测输出：
tables_created
275
安装器日志中还会出现一条字符集提示（实测原文）：
WARN DoliDBMysqli::DoliDBMysqli You should set the $dolibarr_main_db_character_set
and $dolibarr_main_db_collation for the PHP to the same as the database default,
so to utf8mb4 or upgrade database default to utf8.
⚠️ 注意：该 WARN 不影响安装与使用。原因是 24.0 安装器对 MySQL 系驱动刻意固定写入 utf8/utf8_unicode_ci（源码注释：避免 utf8mb4 下 255 字符列索引触及 767 字节上限），属已知设计而非故障。
第四步：管理员账号页（step4）。页面标题与字段（实测回显）：
24.0.2 Dolibarr install or upgrade - Administrator login creation
Dolibarr admin login
Last step : Define here the login and password you wish to use to connect to
Dolibarr. Do not lose this as it is the main account to administer all
other/additional user accounts.
Login : Password : Repeat your password :
填写 admin / q1w2e3r4 并提交。第五步（step5）创建账号并给出收尾提示，实测回显：
Dolibarr administrator login ' admin ' created successfully.
This installation is complete.
Warning, for security reasons, once the installation process is complete, you
must add a file called install.lock into the Dolibarr document directory in
order to prevent the accidental/malicious use of the install tools again.
You need to configure Dolibarr to suit your needs (appearance, features, ...).
To do this, please follow the link below:
Go to Dolibarr (setup area)
💡 说明：与旧版本不同，24.0.2 的安装器不会自动创建 install.lock，而是要求管理员手工落锁——实测确认向导结束后
documents下并无该文件，必须执行 4.8 节。
4.8 落 install.lock 并验证登录
按向导提示创建锁文件并授权：
touch /var/www/dolibarr/documents/install.lock
chown www-data:www-data /var/www/dolibarr/documents/install.lock
ls -l /var/www/dolibarr/documents/install.lock
实测输出：
-rw-r--r-- 1 www-data www-data 0 Oct 22 21:15 /var/www/dolibarr/documents/install.lock
落锁后再次访问 /install/check.php，安装工具已被拦截（实测回显）：
The install/upgrade pages have been disabled for security (by the existence of
a lock file install.lock in the dolibarr documents directory).
If an upgrade is in progress, please wait... If not, you must remove the file
install.lock (or create a file upgrade.unlock for upgrade) into the Dolibarr
documents directory.
最后验证登录链路：浏览器打开 http://<服务器地址>/，用 admin / q1w2e3r4 登录。命令行验证方式（先取登录页 token 再提交）：
TOKEN=$(curl -s -c /tmp/cj.txt http://localhost/index.php \
| grep -oE 'name="token" value="[a-z0-9]+"' | head -1 | grep -oE '[a-z0-9]{20,}')
curl -s -b /tmp/cj.txt -c /tmp/cj.txt -X POST http://localhost/index.php \
-d "token=$TOKEN&actionlogin=login&username=admin&password=q1w2e3r4" \
-o /dev/null -w "login: HTTP %{http_code} -> %{redirect_url}\n"
实测输出（302 跳转管理首页即登录成功）：
login: HTTP 302 -> http://localhost/admin/index.php?mainmenu=home&leftmenu=setup&mesg=setupnotcomplete
登录后管理首页关键信息（实测回显节选）：
Home
...
System administrator : Yes Type: Internal Status : Enabled
Session IP address : 127.0.0.1 Authentication mode: dolibarr
Connected since: 10/22/2026 09:16 PM
Current theme: eldy Current language: en_US
mesg=setupnotcomplete 是新装实例的正常提示（公司信息等基础资料未填），进入「首页 → 设置」补全即可。
4.9 安装收尾：切换生产模式
安装器写入的 $dolibarr_main_prod='0' 是「开发模式」，正式启用前改为 1：
sed -i "s/^\$dolibarr_main_prod='0';/\$dolibarr_main_prod='1';/" /var/www/dolibarr/htdocs/conf/conf.php
grep -n "prod" /var/www/dolibarr/htdocs/conf/conf.php
实测输出：
19:$dolibarr_main_prod='1';
conf.php 为每次请求即时读取，改动无需重启 Apache。验证站点仍正常：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost/index.php
实测输出：
HTTP 200
五、方案 B：官方 zip 分发包安装（备用）
5.1 方案说明
与方案 A 完全同构，唯一差异是把下载物换成 GitHub Release 页的「Source code (zip)」归档（93,802,182 字节），适合 wget 不支持 gzip 流式解压或需在 Windows 上先验包内结构的场景。zip 包结构与 tar.gz 完全相同（顶层目录 dolibarr-24.0.2/，内含 htdocs 与 scripts），解压后的全部步骤照第四章执行即可。
5.2 下载并核对包结构
cd /root
wget https://github.com/Dolibarr/dolibarr/archive/refs/tags/24.0.2.zip
实测输出：
'24.0.2.zip' saved
-rw-r--r-- 1 root root 93802182 Oct 22 21:18 24.0.2.zip
unzip -l 24.0.2.zip | head -8
实测输出：
Archive: dolibarr-24.0.2.zip
7e927764767343334aaa067ca5ec054cfea0a26b
Length Date Time Name
--------- ---------- ----- ----
0 2026-10-02 12:03 dolibarr-24.0.2/
0 2026-10-02 12:03 dolibarr-24.0.2/.agents/
14301 2026-10-02 12:03 dolibarr-24.0.2/.agents/AGENTS.md
0 2026-10-02 12:03 dolibarr-24.0.2/.agents/agents/
5.3 部署差异
unzip -q 24.0.2.zip -d /opt/pkg
mv /opt/pkg/dolibarr-24.0.2 /var/www/dolibarr
之后的建库授权、Apache 站点、安装向导、落锁收尾与 4.5~4.9 节逐字相同，不再重复。
六、方案对比与选择建议
| 维度 | 方案 A：tar.gz + LAMP | 方案 B：zip + LAMP | Docker Compose（另见 B2 篇） |
|---|---|---|---|
| 版本 | 24.0.2 | 24.0.2 | 24.0.2 官方镜像 |
| 是否需联网 | 下载阶段需 | 下载阶段需 | 拉镜像需，之后可离线 |
| 安装方式 | apt + wget + tar + 向导 | wget + unzip + 向导 | compose 一键起库与应用 |
| 数据库 | 自建 MariaDB 10.6 | 自建 MariaDB 10.6 | 编排内 MariaDB 10.11 |
| 数据落位 | /var/www/dolibarr/documents + 数据库 | 同左 | bind mount 到宿主目录 |
| 升级方式 | 换代码 + /install/ 升级向导 | 同左 | 换镜像 tag |
| 适用 | 物理机/云主机标准部署 | 与 A 等价，纯备用 | 快速验证、容器化运维体系 |
选择建议：可联网的标准服务器选方案 A；网络受限场景在能联网的机器下载 tar.gz 后离线传输，安装流程不变；已有容器平台的团队直接用 Compose 镜像方案，库与应用同栈编排、初始化全自动。
七、配置说明
安装完成后与日常运维直接相关的三个落点：
- 主配置文件
/var/www/dolibarr/htdocs/conf/conf.php：数据库连接、路径、认证、生产开关等全部主参数；由安装器生成，逐项含义、加密口令（crypted:/dolcrypt:前缀）与安全参数详见本站《Dolibarr 24.0 配置参数详解》。改完即生效（每次请求即时读取），无需重启 Web 服务；但语法必须正确，写坏一行即全站白屏（实测排障见第九章 FAQ）。 - 数据目录
/var/www/dolibarr/documents：上传文件、生成的单据 PDF、备份文件、install.lock 都在这里。实测初始化后自动生成业务子目录：
find /var/www/dolibarr/documents -maxdepth 1 | sort | head -10
实测输出：
/var/www/dolibarr/documents
/var/www/dolibarr/documents/admin
/var/www/dolibarr/documents/ecm
/var/www/dolibarr/documents/export
/var/www/dolibarr/documents/facture
/var/www/dolibarr/documents/ficheinter
/var/www/dolibarr/documents/import
/var/www/dolibarr/documents/mycompany
/var/www/dolibarr/documents/produit
/var/www/dolibarr/documents/propale
- 应用级参数
llx_const表：界面里「设置」保存的开关（模块启停、公司信息等）存于数据库而非 conf.php，两者分工与常用键详见配置详解篇。
八、升级与多版本管理
8.1 24.0.x 补丁版升级（官方流程）
以 24.0.1 → 24.0.2 为例，官方流程四步：
- 备份：
mariadb-dump全库 + 打包documents目录（CLI 自动备份可用官方 cron 任务，见 D1 篇实测）：mariadb-dump -udolibarr -pq1w2e3r4 dolibarr > /root/dolibarr-backup.sql tar czf /root/documents-backup.tgz -C /var/www/dolibarr documents - 换代码：下载新版 tar.gz 解压，将新
htdocs与scripts覆盖到/var/www/dolibarr（保留htdocs/conf/conf.php与documents），并恢复conf.php与documents属主； - 开升级通道：临时移除
install.lock（或按自检页提示创建upgrade.unlock），浏览器进入http://<服务器地址>/install/index.php?action=upgrade，向导会显示版本从/到（versionfrom/versionto）并执行结构升级脚本（upgrade.php/upgrade2.php）； - 重新上锁：升级完成后在
documents下重建install.lock（后台对应入口为「首页 → 设置 → 工具 → 更新/还原锁」，界面原文即RemoveLock $dolibarrdataroot/install.lock与RestoreLock）。
⚠️ 注意：24.0 线内补丁版无库结构变更，
upgrade向导会秒过；跨大版本（如 23.x → 24.x）必须严格按官方 Wiki 逐版本升级，禁止跳版本。
8.2 多版本并存
tar.gz 部署天然支持多版本并存：将各版本解压为 /var/www/dolibarr-24.0.1、/var/www/dolibarr-24.0.2，各自独立数据库与 documents 目录，用不同虚拟主机端口/域名并行运行，验证无误后切换。同一台机器同时只应有一个版本写同一个库。
九、常见问题（FAQ）
Q1：访问站点出现 PHP 源码而非页面，安装页直接显示 <?php 开头的代码？
现象（实测）：curl http://localhost/install/ 返回的是安装器源码而非 HTML。
定位：只装了 php-cli，Apache 缺少 PHP SAPI 模块。
解决：安装 libapache2-mod-php 并重启 Apache：
DEBIAN_FRONTEND=noninteractive apt-get install -y libapache2-mod-php
systemctl restart apache2
实测输出：
Setting up libapache2-mod-php8.1 (8.1.2-1ubuntu2.28) ...
Setting up libapache2-mod-php (2:8.1+92ubuntu1) ...
重启后首页即恢复正常 302 跳转（Location: install/index.php）。
Q2：安装向导 step1 报「Configuration file htdocs/conf/conf.php is not writable」？ 原因：安装器要求 conf.php 文件已存在且 Web 运行用户可写，24.0 不会自动创建该文件。 解决（实测有效）：
touch /var/www/dolibarr/htdocs/conf/conf.php
chown www-data:www-data /var/www/dolibarr/htdocs/conf/conf.php
Q3：手改 conf.php 后全站白屏，HTTP 200 但页面零字节？
现象（实测）：把 $dolibarr_main_force_https='0'; 手改出错后，所有页面返回空体。
定位：查看站点错误日志——
tail -1 /var/log/apache2/dolibarr_error.log
实测输出：
[Thu Oct 22 21:23:31.049703 2026] [php:error] [pid 13926] [client 127.0.0.1:45358] PHP Parse error: syntax error, unexpected token ";" in /var/www/dolibarr/htdocs/conf/conf.php on line 28
解决：按报错行号修正 PHP 语法（实测修正第 28 行后立即恢复 HTTP 200）。教训：conf.php 每次编辑后先 php -l /var/www/dolibarr/htdocs/conf/conf.php 做语法检查。
Q4：建表阶段日志出现 utf8mb4 相关 WARN？
实测原文见 4.7 节。这是 24.0 安装器有意固定 utf8 字符集（规避索引长度限制）的已知行为，非故障；如需 utf8mb4 表可在初始化后另行评估迁移，普通场景无需处理。
Q5：管理员口令遗失如何重置？
实测有效方法：24.0 默认以 password_hash（bcrypt，$2y$ 前缀）存储口令，同时登录验证兼容传统 MD5 散列（官方 Docker 镜像的初始化脚本即以 MD5 写入初始口令，注释中留有 TODO Generate pass_crypted using PHP password_hash）。因此可直接重置为 MD5 形式：
mariadb -udolibarr -pq1w2e3r4 dolibarr \
-e "UPDATE llx_user SET pass_crypted=MD5('q1w2e3r4') WHERE login='admin';"
实测验证：重置前后分别用新旧口令登录，旧口令返回 HTTP 200（失败停留在登录页），新口令返回 HTTP 302 -> http://localhost/admin/index.php?mainmenu=home（成功）。
Q6：安装完成后 /install/ 仍可访问吗？
不可。落 install.lock 后实测访问 /install/check.php 返回安全拦截页（原文见 4.8 节）；升级时按提示改用 upgrade.unlock 放行。
十、卸载与清理
按「数据 → 应用 → Web 配置 → 可选组件」顺序逐项执行：
# 1) 备份后删除数据库与业务账号
mariadb-dump -udolibarr -pq1w2e3r4 dolibarr > /root/dolibarr-final-backup.sql
mariadb -uroot -e "DROP DATABASE dolibarr;"
mariadb -uroot -e "DROP USER 'dolibarr'@'localhost';"
# 2) 删除应用与数据目录
rm -rf /var/www/dolibarr
# 3) 停用并删除 Apache 站点
a2dissite dolibarr
rm -f /etc/apache2/sites-available/dolibarr.conf
systemctl reload apache2
# 4)（可选，整机不再使用时）卸载 LAMP 组件
apt-get purge -y apache2 mariadb-server libapache2-mod-php
apt-get autoremove -y
十一、参考链接
- 本站《Dolibarr 24.0 介绍与选型指南》：https://www.quzuo.net/document/aRdvi200NGPT（版本节奏、社区规模与选型对比）
- 本站《Dolibarr Docker Compose 部署指南》：容器化部署与自动初始化实测
- 本站《Dolibarr 24.0 配置参数详解》：conf.php 逐项参数、口令加密与安全参数
- 本站《Dolibarr 24.0 常用 CLI 命令与工具详解》：cron 引擎、备份恢复与批处理脚本实测
- 官方发布页：https://github.com/Dolibarr/dolibarr/releases（24.0.2 Source code 归档包下载入口）
- 官方安装教程 Wiki：https://wiki.dolibarr.org/index.php/Installation_tutorial
- 官方运行环境前置 Wiki：https://wiki.dolibarr.org/index.php/Prerequisites
- 本篇实测环境：Ubuntu 22.04.5 LTS / Apache 2.4.52 / PHP 8.1.2 / MariaDB 10.6.23 / Dolibarr 24.0.2