Inventaire 5.1.1 Docker Compose 部署指南

目标：使用官方 docker-inventaire 套件，以 Docker Compose 在 Ubuntu 22.04 服务器上编排部署 Inventaire 5.1.1（服务端 + CouchDB + Elasticsearch + Nginx + Certbot 全家桶），完成配置、启动、初始化验证与日常运维。本文全部命令与回显均在 Ubuntu 22.04.5 LTS + Docker 28.x + Compose v2 实测环境中执行通过，实测日期 2026-10-23。

一、环境信息

本文实测环境如下，读者在同等条件下可直接复现：

说明：官方套件支持两种启动形态——生产形态（全部 5 个服务，Nginx 占用 80/443 并负责 TLS 终结）与本地测试形态（只启动 Inventaire + CouchDB + Elasticsearch 三个核心服务，HTTP 直连）。本文主测本地直连形态（无需域名与 TLS 证书即可完整验证），并在正文给出生产形态的结构说明与差异点。

二、镜像选型说明

docker-inventaire 套件共涉及 5 个服务，镜像来源与版本策略如下：

镜像选型要点：

1. Inventaire 主镜像必须锁版本。官方镜像标签与套件代码存在配套关系（例如 entrypoint 脚本生成的 local.js 字段结构），混搭新旧版本可能出现启动失败。本文实测锁定 5.1.1。
2. CouchDB 与 Elasticsearch 的版本由套件决定，不建议单独升级。Inventaire 对 CouchDB 视图文档（design documents）与 ES 索引结构有明确假设，跨大版本升级需要按官方升级文档执行数据迁移。
3. 若需要从源码自建 Inventaire 镜像（离线环境/定制补丁），套件仓库内自带 inventaire/Dockerfile.inventaire，取消 compose 中 build: 段注释即可切换，本文不展开。

三、前置条件

硬件要求（官方 README 给出的最低值，本文实测环境满足）：

• 4 GB 内存（Elasticsearch 默认堆内存 512 MB + CouchDB + Node 服务，实测三容器常驻内存合计约 1.2 GB，4 GB 富余）
• 10 GB 可用磁盘
• 服务器需可访问外网拉取镜像

软件要求：

# Docker Engine >= v22.0 且 Compose v2 可用
docker --version
docker compose version

实测回显：

Docker version 28.3.3, build 9805876
Docker Compose version v2.39.4

网络与端口规划：

官方 compose 对 CouchDB 的 ports: 段默认整体注释，注释中明确提示：把 5984 映射到宿主机可能绕过防火墙规则（Docker 的 iptables 直插规则优先于 ufw），如无排障需求建议保持注释状态。

目录规划：所有部署文件集中在一个部署目录（本文用 /opt/data/quzuo/tmp/inventaire/b2-stack/），套件仓库克隆、.env、compose 覆盖文件均在此目录内。

四、部署步骤

4.1 获取官方套件

cd /opt/data/quzuo/tmp/inventaire
git clone https://github.com/inventaire/docker-inventaire.git b2-docker-inventaire
cd b2-docker-inventaire

实测回显（节选）：

Cloning into 'b2-docker-inventaire'...
remote: Enumerating objects: 236, done.
Receiving objects: 100% (236/236), 51.42 KiB | 1.10 MiB/s, done.
Resolving deltas: 100% (117/117), done.

4.2 初始化 .env 配置

cp dotenv .env

然后编辑 .env，本文实测将以下变量改为本地测试值（变量含义详见第六章）：

PUBLIC_HOSTNAME=localhost
COUCHDB_USER=admin
COUCHDB_PASSWORD=q1w2e3r4

生产环境要点：PUBLIC_HOSTNAME 填真实域名；COUCHDB_PASSWORD 官方建议不少于 32 位随机串（cat /dev/urandom | tr -dc A-Za-z0-9-_ | head -c 32）；MAILER_SMTP_* 六个邮件变量与 MAP_TILES_ACCESS_TOKEN 必须填写（可为占位值，但不能为空，原因见第九章「等价 docker run」中对 entrypoint 的实测说明）。

同时将 docker-compose.yml 中 inventaire 服务的镜像从 inventaire/inventaire:latest 固定为 inventaire/inventaire:5.1.1。

4.3 编写 compose 覆盖文件（本地 HTTP 直连形态）

本地测试形态需要三处覆盖：固定镜像版本之外的端口映射、HTTP 会话 Cookie 所需的 NODE_CONFIG 注入、以及自定义网络。在部署目录新建 compose.override.yml：

name: inventaire-511-b2-stack
services:
  inventaire:
    ports:
      - "8138:3016"
    environment:
      NODE_CONFIG: >-
        {"serveStaticFiles":true,"publicProtocol":"http","publicHostname":"localhost","publicPort":null}
  couchdb:
    ports:
      - "8139:5984"
networks:
  default:
    name: inventaire-b2-net
    ipam:
      config:
        - subnet: 10.89.66.0/24

三个关键点（均为本文实测得出的结论）：

1. NODE_CONFIG 必须注入 publicProtocol":"http"：官方镜像默认以 NODE_ENV=production + NODE_APP_INSTANCE=federated 运行，服务端会话 Cookie 的 secure 属性取值与 publicProtocol 绑定（secure: publicProtocol === 'https'）。HTTP 直连时若不覆盖，登录接口虽返回 {"ok":true} 但会话 Cookie 不会下发，后续所有需认证的 API 一律 401。实测注入后登录与认证立即恢复正常。
2. serveStaticFiles:true：生产形态由 Nginx 托管客户端静态文件，本地直连形态没有 Nginx，必须让 Node 服务自己托管前端页面，否则访问首页只有 API 没有 UI。
3. YAML 写法：NODE_CONFIG 的值是内嵌 JSON，直接写单行字符串会因内部双引号触发 YAML 引号冲突报错（实测报错 yaml: line 9: could not find expected ':'），用块标量 >- 折叠写法最稳。

4.4 启动与首次初始化

本地直连形态只启动核心三服务（官方 README 推荐的本地测试方式）：

docker compose -f docker-compose.yml -f compose.override.yml up -d inventaire

实测回显：

[+] Running 9/9
 ✔ Network inventaire-b2-net            Created
 ✔ Volume "inventaire-511-b2-stack_inventaire-leveldb"            Created
 ✔ Volume "inventaire-511-b2-stack_inventaire-local-media-storage" Created
 ✔ Volume "inventaire-511-b2-stack_inventaire-backups"            Created
 ✔ Volume "inventaire-511-b2-stack_inventaire-server"             Created
 ✔ Volume "inventaire-511-b2-stack_couchdb"                       Created
 ✔ Volume "inventaire-511-b2-stack_elasticsearch"                 Created
 ✔ Container inventaire-511-b2-stack-couchdb-1       Started
 ✔ Container inventaire-511-b2-stack-elasticsearch-1 Started
 ✔ Container inventaire-511-b2-stack-inventaire-1    Started

首次启动时序：CouchDB 与 Elasticsearch 先就绪，Inventaire 启动时自动向 CouchDB 创建全部业务数据库、向 Elasticsearch 创建索引。观察启动日志：

docker compose logs -f inventaire

实测回显（节选，出现 server started 字样即就绪）：

inventaire-1  | CouchDB: initializing design docs in users-prod
inventaire-1  | CouchDB: users-prod design docs initialized
inventaire-1  | GET http://elasticsearch:9200/items-prod [r2] 200 4ms
inventaire-1  | GET http://elasticsearch:9200/groups-prod [r3] 200 4ms
...
inventaire-1  | server started at http://inventaire:3016 (production)

生产形态（含 Nginx/Certbot）的差异：首次启动前需先完成 TLS 证书生成（官方 README 提供一次性 certbot certonly --standalone 命令生成首个证书到 ./certbot/conf/），然后 docker compose up --detach 启动全部服务，入口为 80/443。本文实测环境无公网域名，未执行此形态，配置结构见第八章。

五、数据持久化说明

套件共声明 8 个命名卷，其中随「本地直连形态」实际创建 6 个（nginx/certbot 的 2 个卷随对应服务启动才创建）：

备份建议：核心数据是 couchdb 与 inventaire-leveldb、inventaire-local-media-storage 三个卷，可用 docker run --rm -v <卷名>:/data -v <备份目录>:/backup busybox tar czf /backup/<卷名>.tar.gz -C /data . 方式导出，或直接使用 Inventaire 服务内置的 CouchDB 备份机制（/opt/inventaire_backups 卷即为其落盘位置）。

六、环境变量表

.env 由官方 dotenv 模板复制而来，全部变量如下（实测验证：Inventaire 镜像 entrypoint 以 set -u 严格模式引用其中 24 个变量，任何一个未定义都会导致容器启动即退出）：

注意：.env 中的引号会被 Compose 的 env_file 机制剥除后再传给容器；但 docker run --env-file 不会剥引号，会把单引号字面量传进 entrypoint 的 heredoc，生成非法 JS 配置导致启动失败（实测复现，详见第十一章 FAQ）。

七、配置参数说明

官方镜像的配置加载分三层（按 node-config 的加载顺序，后者覆盖前者）：

1. entrypoint 生成的 dist/config/local.js：容器每次启动时由 /opt/docker-entrypoint.sh 用 .env 的 24 个变量重新生成（模板硬编码 CouchDB 主机名为 couchdb、ES 地址为 http://elasticsearch:9200、LevelDB 目录为 /opt/inventaire_leveldb）。这意味着官方镜像内的 CouchDB/ES 地址不可通过 .env 修改，单容器连接外部数据库需走 NODE_CONFIG 覆盖（见第九章）。

2. NODE_CONFIG 环境变量：node-config 官方机制，JSON 字符串直接覆盖任意配置项，优先级高于 local.js。本地 HTTP 直连形态的必用项：

   配置项	覆盖值	作用
   publicProtocol	http	会话 Cookie 不再标记 Secure，HTTP 直连可正常登录
   publicHostname	localhost	对外主机名与 Cookie 环境后缀
   serveStaticFiles	true	Node 服务直接托管前端静态文件
   publicPort	null	对外端口跟随实际监听端口
   hostname（等价 docker run 场景）	0.0.0.0	监听全部网卡（官方镜像默认监听主机名 inventaire 解析出的地址，见 FAQ）

3. local-production.js（高级）：entrypoint 注释中说明可在卷内放置 ./dist/config/local-production.js，其优先级高于 local.js，适合不想把敏感配置放进环境变量的场景。

各配置项的完整语义（db/leveldb/elasticsearch/mailer/mediaStorage 等全部参数）见本专栏 《Inventaire 5.1.1 配置参数详解》。

八、配置文件挂载

官方套件的配置不通过 bind mount 覆盖，而是「构建时烧入 + 环境变量注入」两条路径：

生产形态的 Nginx 反代结构（来自套件 nginx/templates/default.conf.template，本文实测环境未启用，此处给出结构说明供规划）：443 TLS 终结后，静态文件（root /opt/inventaire/client）与 /img/* 图片缩放缓存（proxy_store 到 nginx-cache 卷实现 try_files 命中）由 Nginx 直接服务，/api 与 JSON/RSS 路由通过 error_page 543 命名位置转发到 inventaire:3016，并注入 X-Forwarded-Proto https 头。80 端口除 /.well-known/ ACME 验证外全部 301 跳转 HTTPS。

九、等价 docker run 形态

不使用 Compose、直接以 docker run 拉起单个 Inventaire 容器连接既有依赖，是理解官方镜像配置机制的捷径，也是某些编排系统（非 Compose）迁移时的过渡形态。以下命令为本文实测通过的完整形态（在同一 Docker 网络内已有 CouchDB 与 Elasticsearch，主机名分别为 couchdb 与 elasticsearch；若两库在其他主机，需用 NODE_CONFIG 覆盖 db.hostname 与 elasticsearch.origin）：

docker run -d --name inventaire \
  --network inventaire-b2-net \
  -p 3016:3016 \
  -e NODE_ENV=production \
  -e NODE_APP_INSTANCE=federated \
  -e INVENTAIRE_PORT=3016 \
  -e PUBLIC_HOSTNAME=localhost \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=q1w2e3r4 \
  -e INSTANCE_NAME='My Inventaire Instance' \
  -e ORG_NAME='Example Organization' \
  -e ORG_URL='https://inventaire.example.org' \
  -e CONTACT_ADDRESS='contact@inventaire.example.org' \
  -e MAILER_SMTP_HOST=smtp.example.org \
  -e MAILER_SMTP_PORT=587 \
  -e MAILER_SMTP_USERNAME=demo \
  -e MAILER_SMTP_PASSWORD=demo \
  -e MAP_TILES_ACCESS_TOKEN=demo \
  -e MOTOMO_ENABLED=false \
  -e MOTOMO_ENDPOINT=https://matomo.example.org/matomo.php \
  -e MOTOMO_IDSITE=1 \
  -e MOTOMO_REC=1 \
  -e MEDIA_STORAGE_MODE=local \
  -e SWIFT_USERNAME=demo \
  -e SWIFT_PASSWORD=demo \
  -e SWIFT_AUTH_URL=https://swift.example.org/auth \
  -e SWIFT_PUBLIC_URL=https://swift.example.org/public \
  -e SWIFT_TENANT_NAME=12345678 \
  -e SWIFT_REGION=SBG-1 \
  -e NODE_CONFIG='{"hostname":"0.0.0.0","serveStaticFiles":true,"publicProtocol":"http","publicHostname":"localhost","publicPort":null}' \
  inventaire/inventaire:5.1.1

验证：

curl -s http://localhost:3016/api/config | head -c 300

实测回显：

{"version":"5.1.1","softwareName":"inventaire","serverGitHeadRev":"3ba29ff","env":"production","instanceName":"My Inventaire Instance","orgName":"Example Organization","orgUrl":"https://inventaire.example.org","remoteEntitiesOrigin":"https://inventaire.io","mapTiles":{"tileUrl":"https://tile.openstreetmap.org/{z}/{x}/{

实测中踩过的四个坑（每一个都足以让容器起不来，排障时按报错对号入座）：

1. 缺任意一个 entrypoint 引用的环境变量 → 启动即退。/opt/docker-entrypoint.sh 开头 set -eu，heredoc 模板引用了上表 24 个变量，缺一个就在第 11 行报 INVENTAIRE_PORT: unbound variable（缺哪个报哪个，本文从缺 1 个到缺 10 个逐步补齐共重试 5 次）。结论：单容器运行必须把 .env 全量变量逐个 -e 传入。
2. docker run --env-file 会破坏带引号的值。实测用 --env-file .env 传参后，.env 中 INSTANCE_NAME='My Inventaire Instance' 的单引号被当作字面量传入，entrypoint heredoc 生成 instanceName: ''My Inventaire Instance''，node-config 解析报 Cannot parse config file: '/opt/inventaire/dist/config/local.js': SyntaxError: Unexpected identifier 'My'。Compose 的 env_file 会剥引号而 docker run --env-file 不会，两者不通用。
3. 监听地址 DNS 冲突 → EADDRNOTAVAIL。官方镜像默认监听主机名 inventaire 解析出的地址；当自定义容器与套件的 inventaire 服务同网络时，Docker 内嵌 DNS 把 inventaire 解析到套件容器的 IP，自定义容器试图 listen 他人 IP 报 Error: listen EADDRNOTAVAIL: address not available 10.89.66.4:3016。解决：NODE_CONFIG 注入 "hostname":"0.0.0.0"。
4. HTTP 直连必须覆盖 publicProtocol：不覆盖时登录后 Cookie 不下发，需认证接口全部 401（详见第七章）。

结论：等价 docker run 完全可行但变量必须一个不少，这正是官方套件坚持用 env_file: .env 的原因——生产部署建议优先 Compose 形态。

十、常用运维命令

以下命令均在实测栈（项目名 inventaire-511-b2-stack）中验证：

# 查看服务状态与版本
docker compose ps
curl -s http://localhost:8138/api/config | python3 -m json.tool | head -8

# 跟踪日志（服务端日志内含 CouchDB/ES 的请求级输出）
docker compose logs -f inventaire
docker compose logs --tail 200 couchdb

# 重启单个服务
docker compose restart inventaire

# 拉取镜像更新（不立即生效）
docker compose pull

版本升级流程（官方 README 的 Update 段，逐条命令含义如下）：

cd docker-inventaire
git pull origin main                                  # 套件更新（可能含 compose/镜像配套变更）
docker compose pull                                   # 拉新镜像
docker compose down                                   # 停止并移除旧容器（卷保留）
docker volume rm docker-inventaire_inventaire-server  # 删除程序文件卷，让新镜像重建（数据卷不动）
docker compose up --detach                            # 以新镜像重启
docker compose logs --follow --tail 500 inventaire    # 观察启动与数据库迁移日志

升级前先访问 /api/config 记下当前版本，对照官方 CHANGELOG 检查是否有标记「requires data transformation」的破坏性变更；有则需要按官方文档对 CouchDB 数据做导出-转换-重导。删除 inventaire-server 卷是官方设计的更新机制（程序与数据分卷的原因），不影响 LevelDB/图片/数据库数据。

卸载与清理：

docker compose down -v     # 停止并删除容器与全部命名卷（含数据库数据，慎重）
docker network rm inventaire-b2-net

十一、常见问题

Q1：登录返回 {"ok":true} 但后续接口全部 401？

HTTP 直连（非 HTTPS）场景未覆盖 publicProtocol。服务端会话中间件按 secure: publicProtocol === 'https' 设置 Cookie 的 Secure 标记，浏览器/客户端在 HTTP 连接上不会回传 Secure Cookie，服务端判定未登录。实测在 NODE_CONFIG 注入 "publicProtocol":"http" 后恢复正常（登录后 GET /api/user 返回完整用户对象）。生产走 Nginx TLS 终结时不存在此问题。

Q2：docker compose up 报 yaml: line N: could not find expected ':'？

NODE_CONFIG 的 JSON 值与 YAML 双引号嵌套冲突，用块标量 >- 写法（见 4.3 节）。

Q3：/api/search?types=works&... 返回 entities should be searched on remote instance？

.env 默认 NODE_APP_INSTANCE=federated（联邦实例模式），图书/著作/人物等实体检索会被重定向到旗舰实例 inventaire.io（实测返回 {"status":400,"message":"entities should be searched on remote instance","context":{"types":["works"],"remoteEntitiesOrigin":"https://inventaire.io",...}}）。联邦实例本地仍可搜索用户与小组（实测 types=users&search=admin 正常返回结果与 _score 评分）。若需要完全本地化的实体索引检索，需改用非联邦模式运行并自行导入实体数据。

Q4：Elasticsearch 启动报 max virtual memory areas vm.max_map_count [65530] is too low？

宿主机内核参数过低（官方 README 排障段收录），在宿主机执行 sudo sysctl -w vm.max_map_count=262144，并写入 /etc/sysctl.conf 持久化。

Q5：容器反复重启，日志有 unbound variable 或 Cannot parse config file ... local.js？

环境变量不全（逐个补齐 24 个）或经 docker run --env-file 传入时引号未剥（见第九章坑 1、坑 2）。

Q6：listen EADDRNOTAVAIL: address not available 10.89.x.x:3016？

容器主机名 inventaire 在所在网络中被解析到其他容器（常见于自定义容器接入套件网络的场景），用 NODE_CONFIG 注入 "hostname":"0.0.0.0" 修复（见第九章坑 3）。

Q7：CouchDB 管理界面 Fauxton 如何访问？

临时排障可按 4.3 节给 couchdb 服务加端口映射后访问 http://<主机>:<映射端口>/_utils/；官方注释明确提醒映射到宿主机可能绕过防火墙，用完即撤。

十二、参考链接

• 官方套件仓库（compose 定义、Nginx 模板、dotenv 模板）：https://github.com/inventaire/docker-inventaire
• 官方 Inventaire 镜像（Docker Hub）：https://hub.docker.com/r/inventaire/inventaire
• 服务端主仓库（CHANGELOG 与 docs/administration 目录）：https://codeberg.org/inventaire/inventaire
• 部署脚本仓库（非容器形态的 systemd 部署）：https://codeberg.org/inventaire/inventaire-deploy
• node-config 环境变量覆盖机制：https://github.com/node-config/node-config/wiki/Environment-Variables#node_config
• CouchDB 磁盘与文件系统性能（套件 ERL_FLAGS 注释出处）：https://docs.couchdb.org/en/stable/maintenance/performance.html
• Elasticsearch Docker 官方文档（vm.max_map_count 等）：https://www.elastic.co/guide/en/elasticsearch/reference/7.17/docker.html
• 本专栏姊妹篇：《Inventaire 5.1.1 介绍与选型指南》、《Inventaire 5.1.1 配置参数详解》、《Inventaire 5.1.1 API 详解》