LedgerSMB 1.13.8 Docker Compose 部署指南

目标：在一台 Linux 服务器上，用官方 ledgersmb/ledgersmb:1.13.8 与官方编排样例为骨架，从零部署一套可登录使用的 LedgerSMB + PostgreSQL 环境，并完成首次建账（公司账套、科目表、初始管理员）。本文全部命令与回显来自 2026-10-24 实测（服务器时区 UTC，日志时间为 UTC，对应北京时间同日晚间）。

一、环境信息

实测环境与版本基线：

项	值
LedgerSMB 版本	1.13.8（当前稳定版，官方镜像）
数据库	PostgreSQL 15（官方 1.13 编排样例使用 postgres:15-alpine；1.13 最低要求 PostgreSQL 13+）
应用运行方式	镜像内置 nginx（1.26.3，80 端口，静态资源加速）+ Starman PSGI 应用服务（5762 端口）
编排工具	docker compose（v2）
实测主机端口	8130 → 应用 5762
实测网络	独立网络 ledgersmb-1138-net，网段 10.89.72.0/24

官方交付形态说明（实查 ledgersmb-docker 仓库 README，2026-10-24）：镜像同时监听 80（内置 nginx 反代，含静态资源缓存，生产推荐）与 5762（Starman 直连，评估够用）两个端口；另有无反代的 -base 后缀标签。本文为让路径最短，直接映射 5762；上生产时把宿主 80/443 指到镜像 80 端口并在前面加 TLS 终结即可。

二、前置条件

服务器已安装 Docker 与 docker compose 插件。
拉取官方镜像（版本固定为 1.13.8）：

docker pull ledgersmb/ledgersmb:1.13.8
# 1.13.8: Pulling from ledgersmb/ledgersmb
# Digest: sha256:f86e78f3bdd6e20ec648ea3da22a583ce2c3a63ed1f871a9777a05ff1b2057ce
# Status: Downloaded newer image for ledgersmb/ledgersmb:1.13.8
docker images ledgersmb/ledgersmb
# REPOSITORY             TAG      IMAGE ID       CREATED       SIZE
# ledgersmb/ledgersmb    1.13.8   f86e78f3bdd6   7 weeks ago   1.36GB

规划网络与目录（本例：网络 ledgersmb-1138-net / 10.89.72.0/24；数据目录与编排文件集中于一个工作目录）：

docker network create --subnet 10.89.72.0/24 ledgersmb-1138-net
mkdir -p /srv/ledgersmb/pgdata /srv/ledgersmb/stack && cd /srv/ledgersmb/stack

⚠️ 注意：创建网络前先用 docker network ls 配合 docker network inspect <名> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' 排查目标网段是否已被其他业务占用，避免网段冲突。

三、编排文件

以下编排以官方 ledgersmb-docker 仓库 1.13 分支样例为骨架（官方样例要点：数据库服务名必须叫 postgres，因为应用默认以主机名 postgres 寻库；数据落在 pgdata 卷以便升级不丢数据），做了三点本地化：固定版本号、固定项目名与网络、数据目录改为宿主机 bind 挂载便于备份。

docker-compose.yml：

name: ledgersmb-1.13.8-stack

services:
  postgres:
    image: postgres:15-alpine
    hostname: postgres
    environment:
      POSTGRES_PASSWORD: q1w2e3r4          # 演示口令，生产请换成强口令
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - /srv/ledgersmb/pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - internal

  lsmb:
    depends_on:
      - postgres
    image: ledgersmb/ledgersmb:1.13.8
    ports:
      - "8130:5762"                        # 宿主 8130 -> 应用 5762
    environment:
      LSMB_WORKERS: 5                      # HTTP 工作进程数，默认 2，小内存机器可调低
    restart: unless-stopped
    networks:
      - internal

networks:
  internal:
    external: true
    name: ledgersmb-1138-net

关键配置解读（与官方镜像文档一致，实查 2026-10-24）：

配置	说明
服务名 `postgres`	应用默认 `POSTGRES_HOST=postgres`，服务名即主机名，必须一致（官方样例同名约定）
`PGDATA` 指到子目录	官方样例做法：把 PGDATA 定位到挂载目录下的 pgdata 子目录，避免该类镜像常见的 lost+found 干扰
`LSMB_WORKERS`	处理 HTTP 请求的进程数；官方默认 2（面向 1GB 小内存），本文设 5
`LSMB_MAIL_*` 环境变量	可选邮件配置（LSMB_MAIL_SMTPHOST/SMTPPORT/SMTPTLS/SMTPSENDER_HOSTNAME/SMTPUSER/SMTPPASS/SMTPAUTHMECH），不配则系统内发信走本机投递
`PROXY_IP`	若由宿主上的反向代理做 TLS 终结，设为代理地址段以正确还原客户端 IP
配置外置	把配置目录 bind 到应用 `/srv/ledgersmb/local/conf` 可在重启间修改 ledgersmb.yaml（详见配置篇）

四、启动

cd /srv/ledgersmb/stack && docker compose up -d

实测启动后状态：

docker compose ps
# NAME                              IMAGE                        COMMAND    SERVICE    CREATED          STATUS          PORTS
# ledgersmb-1138-stack-lsmb-1       ledgersmb/ledgersmb:1.13.8   "/init"    lsmb       11 minutes ago   Up 11 minutes   80/tcp, 0.0.0.0:8130->5762/tcp, [::]:8130->5762/tcp
# ledgersmb-1138-stack-postgres-1   postgres:15-alpine           "docker-entrypoint.s…"  postgres  11 minutes ago  Up 11 minutes   5432/tcp

应用进程启动日志（实测摘录，可看到 nginx 与 Starman 两个进程都在位）：

docker compose logs lsmb | tail
# services-up: info: copying legacy longrun nginx (no readiness notification)
# 2026/10/23 19:30:25 [notice] 80#80: nginx/1.26.3
# 2026/10/23-19:30:27 Starman::Server (type Net::Server::PreFork) starting! pid(86)

就绪验收：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8130/login.pl
# 200

五、首次建账（setup.pl 数据库管理台）

LedgerSMB 的"管理员入口"与"业务入口"是分开的：setup.pl 用 PostgreSQL 数据库管理员账号登录，负责创建/维护公司数据库；日常业务用 login.pl 登录。官方流程文档见 https://ledgersmb.org/content/preparing-ledgersmb-113-first-use（实查 2026-10-24）。

5.1 访问管理台并确认建库

浏览器打开 http://<服务器IP>:8130/setup.pl，用数据库管理员凭据登录（本例用户 postgres，口令为编排文件中的 POSTGRES_PASSWORD）。选择数据库（公司账套名）demo1，系统提示该库不存在并询问是否创建——确认创建后即完成空库初始化（实测页面文案：Database does not exist. Create Database?）。

命令行等价操作（与页面交互等价的 HTTP 请求，便于自动化）：

# setup.pl 使用 HTTP Basic 认证；database 参数即公司账套名
curl -s -u postgres:q1w2e3r4 "http://localhost:8130/setup.pl?action=login&database=demo1" | grep -oE 'La base de datos[^<]*|Database[^<]{0,40}'
# Database does not exist. Create Database?（实测回显，界面语言取决于设置）

5.2 重建模块（可选但推荐）

首次建库后，管理台提供 "Reload menu / Rebuild modules" 操作。实测执行 rebuild_modules 成功后页面显示：

Database Operation Complete
This database operation has completed successfully. LedgerSMB may now be used.

5.3 装载科目表（Chart of Accounts）

在管理台选择国家/地区科目表。实测：先选区域 cn（中国），再选该区域下唯一的科目表 General.xml 完成装载。命令行等价流程为三次请求（页面登录态下依次为 select_coa 选区域 → 选科目表文件），区域列表实测含 de/ar/au/at/br/be/ca/cz/cn/co/dk/eg/es/us/fr/hu/id/it/lv/no/nz/py/nl/pl/gb/se/ch/tw/ve 共 29 个。

💡 说明：科目表决定会计科目骨架，装载后仍可在系统内自行增删科目；选 cn 只影响预置科目与区域设置，不影响后续把界面语言切成中文。

5.4 装载单据模板

管理台 "Templates → Load Templates" 实测可选模板目录 demo（销售/采购/总账单据的 HTML/LaTeX 模板），装载完成返回管理台首页。模板决定后续发票、订单等单据的打印版式，可在配置篇所述的模板目录中替换。

5.5 创建初始管理员

管理台 "Users → Agregar Usuario（添加用户）"：填写用户名 admin、口令、姓名、日期（格式 yyyy-mm-dd）、所属国家与权限（选 Full permissions，即 1 全权限），提交后完成公司库内管理员与菜单元数据的初始化。实测提交成功后页面显示数据库统计：

Database Operation Complete
LedgerSMB Database Statistics (Row counts)
  CxP 0   CxC 0   Customer/Vendor Accounts 0   Libro Mayor General 0
  Invoice Lines 0   Journal Lines 0   Orders 0   Users 1

Users 1 即初始管理员已建好。命令行等价提交（页面表单的 __action=_create_initial_user，含 perms=1 全权限）实测返回同一完成页。

5.6 数据库侧验证

docker exec ledgersmb-1138-stack-postgres-1 psql -U postgres -c '\l'
#    Name    |  Owner   | Encoding |  Collate   |  Ctype    |
# -----------+----------+----------+------------+-----------
#  demo1     | postgres | UTF8     | en_US.utf8 | en_US.utf8 |
#  postgres  | postgres | UTF8     | en_US.utf8 | en_US.utf8 |
#  template0 | postgres | UTF8     | en_US.utf8 | en_US.utf8 |
#  template1 | postgres | UTF8     | en_US.utf8 | en_US.utf8 |

公司账套 = 独立数据库（demo1）；psql -U postgres -c '\du' 中可见 admin 角色，其成员关系为 lsmb_demo1__base_user 及数百个 lsmb_demo1__* 细粒度权限角色（应收/应付/总账/库存/资产等），印证 LedgerSMB"权限角色建在数据库内核"的架构。

六、登录业务端验收

# 业务端登录是 JSON 认证接口（官方 API 文档同款入口）：
curl -s -X POST 'http://localhost:8130/login.pl?__action=authenticate' \
  -H 'Content-Type: application/json' \
  -d '{"login":"admin","password":"q1w2e3r4","company":"demo1"}'
# { "target":  "e368b9938746fa090d6afd3628355133/erp.pl?user=admin" }

返回的 target 为业务端会话路径（公司名的 MD5 摘要，echo -n demo1 | md5sum = e368b9938746fa090d6afd3628355133，实测一致）。浏览器直接访问 http://<服务器IP>:8130/login.pl 输入同样三要素（用户/口令/公司 demo1）即可进入操作菜单。

⚠️ Safari 浏览器仅支持 HTTPS 访问（官方 1.13 README 明示），生产环境请在编排前先规划 TLS：常见做法是宿主前置 nginx/traefik 终结 HTTPS，再转发到应用 80 或 5762 端口。

七、数据持久化、备份与升级

持久化：所有业务数据只在 PostgreSQL 中（demo1 库），应用本体无状态；宿主目录 /srv/ledgersmb/pgdata 承载数据。升级应用版本不动数据库卷即不丢数据（官方编排样例注释原话：数据跨升级持久化依赖 pgdata 卷）。
备份：首选逻辑备份 pg_dump：

docker exec ledgersmb-1138-stack-postgres-1 \
  pg_dump -U postgres -Fc demo1 > demo1-$(date +%F).dump

也可用 setup.pl 管理台的 "Respaldo → Backup DB / Backup Roles" 直接下载 SQL 备份与角色备份（实测菜单项在位）。 3. 升级：把编排文件中的镜像 tag 换到新版本（如 1.13.9）后：

docker compose pull lsmb && docker compose up -d

首次访问时 LedgerSMB 会在 setup.pl / 应用层自动执行 schema 重构（实测日志有 "rebuild/upgrade" 工作流）。跨大版本（1.12 → 1.13）前先完整备份，并核对官方版本公告的数据库兼容要求。 4. 多公司：需要第二家公司时，在 setup.pl 再建一个库（如 demo2）即可，登录时公司名填对应库名——这正是"一个公司一个库"的多公司模型。

八、常见问题排查

现象	原因与处理
`login.pl` 返回 502/503	应用进程未就绪（Starman 启动约需数秒），`docker compose logs lsmb` 看到两个进程（nginx/Starman）起来再试
setup.pl 登录 401	Basic 认证凭据错误，或与编排文件 POSTGRES_PASSWORD 不一致
建库卡住/报错	检查应用能否解析主机名 postgres：确认服务名、同网络；`docker compose exec lsmb ping -c1 postgres` 验证
数据库连接被拒	postgres 容器未就绪或口令不符；确认 `depends_on` 与 POSTGRES_PASSWORD
端口冲突	8130 被占用时换宿主端口即可，映射只需改 `ports` 前半段
忘记 setup 口令	即 POSTGRES_PASSWORD，重置需改编排后重建数据库口令（数据不丢，见配置篇口令管理）

九、卸载

cd /srv/ledgersmb/stack
docker compose down            # 停止并移除编排资源（数据目录保留）
# 确认不再需要数据后：
rm -rf /srv/ledgersmb/pgdata   # 删除数据目录（不可逆）
docker network rm ledgersmb-1138-net

十、参考

官方编排样例（1.13 分支）：https://github.com/ledgersmb/ledgersmb-docker/blob/1.13/docker-compose.yml
官方镜像使用文档（环境变量全表）：https://github.com/ledgersmb/ledgersmb-docker/blob/1.13/README.md
Docker Hub 镜像页：https://hub.docker.com/r/ledgersmb/ledgersmb/
首次使用准备指引：https://ledgersmb.org/content/preparing-ledgersmb-113-first-use
本专栏同系列：产品认知见《LedgerSMB 1.13.8 介绍与选型指南》；配置项精读见《LedgerSMB 1.13.8 配置参数详解》；HTTP 接口调用见《LedgerSMB 1.13.8 API 使用详解》。