AmuseWiki Docker Compose 部署指南

目标：用 Docker Compose 从零部署 AmuseWiki 2.611 文学文本 wiki 农场——完成首个站点初始化、多站点农场扩容、内容导入导出与 EPUB 出版输出验证，已在 Debian 12 宿主机（Docker Compose v5.6.1）实测通过。软件定位与选型对比见本专栏《AmuseWiki 介绍与选型指南》篇。

一、环境信息

部署宿主：Debian 12 (bookworm) x86_64，Docker Compose（com.docker.compose.version: 5.6.1）
应用镜像：rojen/amusewiki:package（AmuseWikiFarm 2.611，镜像内 dpkg 包 amusewiki 2.611-1+amw1，未压缩 3.41GB）
版本线：官方最新稳定版 2.619（官方 GitHub Changes 2026-10-10 + deb.amusewiki.org 池内 amusewiki_2.619-1_all.deb 双源实查，2026-11-01；GitHub Releases 页记录滞后一拍停在 v_2.618）；Docker package 镜像线当前停在 2.611（Docker Hub package-2.611 发布于 2026-01-06）
服务栈：nginx（监听 80/443）+ Plack FCGI（Perl，unix socket /var/lib/amusewiki/amusewiki.socket）+ jobber 作业队列 + Xapian 全文索引 + TeX Live 精简版（amusewiki-texlive 20240128-1，PDF 编译）
数据库：SQLite（/var/lib/dbconfig-common/sqlite3/amusewiki/amusewiki，schema 版本 87）；应用亦支持 PostgreSQL/MySQL/MariaDB
端口映射：宿主 8140 → 应用 80
网络：自定义 bridge 网段 10.89.60.0/24，应用节点固定地址 10.89.60.10
持久化目录：项目目录下 data/repo、data/thumbnails、data/staging、data/db、data/sites 五个 bind mount
演示管理账号：admin / q1w2e3r4（root 角色）

二、镜像选型说明

AmuseWiki 官方推荐的安装路径是 Debian 包（deb.amusewiki.org，2026-05-01 起从 packages.amusewiki.org 迁移），Docker 镜像 rojen/amusewiki 是官方维护的容器化变体，Docker Hub 标签实测（2026-11-01，经代理查询 hub.docker.com/v2 API）：

标签	对应版本	更新时间	压缩体积	说明
`package` / `latest` / `package-2.611`	2.611	2026-01-06	1.08GB	基于官方 Debian 包，内含精简 TeX Live，可编译 PDF
`texlive-minimal` / `texlive-minimal-2.611`	2.611	2026-07-08	1.32GB	最小 TeX Live，PDF 能力受限
`texlive-base`	2.611 系	2026-07-09	2.03GB	中等 TeX Live
`texlive-full`	2.611 系	2026-07-09	6.06GB	完整 TeX Live，排版兼容性最好
`package-2.606` / `package-2.605` / `package-2.603` …	旧版	2025-07~2025-02	≈1.08GB	历史版本线

选型解读：本文采用 package 标签——它直接消费官方 Debian 包（amusewiki 2.611-1+amw1），自带 amusewiki-texlive（精简 TeX Live 2023）与 amusewiki-extra-fonts，EPUB/PDF 出版链路开箱可用；只有当你的书目需要完整 LaTeX 宏包/生僻字体时才上 texlive-full（体积 6 倍）。若需要官方最新 2.619，package 镜像尚未跟进，应走 Debian 包安装路径（见官方 install 文档，本专栏不展开）。

三、前置条件

Docker Engine 与 Compose 可用：

docker compose version
Docker Compose version v5.6.1

宿主端口 8140 未被占用：

ss -ltn | grep 8140
# 无输出即可用

磁盘余量 ≥ 5GB（官方安装文档口径：应用本体约 2.2GB，产出文件多，建议最小 5GB 空闲）。
网络可达性：镜像内初始化需要克隆官方文档仓库（https://amusewiki.org/git/amw 或 https://github.com/melmothx/amusewiki-site.git）。⚠️ 网络说明：本次实测 github.com:443 直连超时（Failed to connect to github.com port 443 after 136372 ms），任务侧常备代理 192.168.1.62:7897 已失效（TCP 不通），代理 192.168.1.72:7897 实测可用（curl 探测返回 400 属代理正常响应）。克隆步骤均按「官方源 → 代理」降级链执行并在对应小节标注。

四、部署步骤

4.1 准备项目目录与 compose 文件

创建项目目录（本文实测路径为工作区约定路径 /opt/data/quzuo/tmp/amusewiki，实际部署可任选目录；compose 内挂载均用相对路径 ./data/...，与绝对路径无关）：

mkdir -p /opt/data/quzuo/tmp/amusewiki/data/{repo,thumbnails,staging,db,sites}
cd /opt/data/quzuo/tmp/amusewiki

docker-compose.yml（实测文件原文）：

name: amusewiki-2.611-stack
services:
  app:
    image: rojen/amusewiki:package
    container_name: amusewiki-2611-web
    hostname: amusewiki.local
    ports:
      - '8140:80'
    environment:
      - POST_DOMAIN=localhost
      - CHANGE_PASSWORD_BEFORE_RUN=true
      - AMW_USERNAME=admin
      - AMW_PASSWORD=q1w2e3r4
      - AMW_WORKERS=3
    volumes:
      - ./data/repo:/var/lib/amusewiki/repo
      - ./data/thumbnails:/var/lib/amusewiki/thumbnails
      - ./data/staging:/var/lib/amusewiki/staging
      - ./data/db:/var/lib/dbconfig-common/sqlite3/amusewiki
      - ./data/sites:/etc/nginx/sites-enabled
    networks:
      amusewiki-net:
        ipv4_address: 10.89.60.10
networks:
  amusewiki-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

逐项说明：

name: 显式项目名（防多项目互删）；实测 compose 会把项目名规范化为 amusewiki-2611-stack（点号被剥离），网络随之命名为 amusewiki-2611-stack_amusewiki-net。
ports 8140:80——应用侧 nginx 监听 80。
environment 五个变量见第六节环境变量表。
volumes 五个 bind mount 覆盖「站点 git 仓库、缩略图、staging 草稿、SQLite 库、nginx 站点目录」，是升级/迁移时唯一需要备份的集合（详见第五节）。
networks 固定子网 10.89.60.0/24 与节点地址，避免与宿主既有网段冲突。

4.2 启动栈

docker compose up -d

实测回显（节选）：

 Container amusewiki-2611-web Created
 Container amusewiki-2611-web Starting
 Container amusewiki-2611-web Started

确认栈状态：

docker compose ps

NAME                 IMAGE                     COMMAND                SERVICE   CREATED         STATUS         PORTS
amusewiki-2611-web   rojen/amusewiki:package   "/usr/bin/systemctl"   app       4 minutes ago   Up 4 minutes   0.0.0.0:8140->80/tcp, [::]:8140->80/tcp

镜像入口为 init 风格进程（/usr/bin/systemctl），开机即拉起已 enable 的 nginx、amusewiki-web、amusewiki-jobber 三个单元。验证服务真实在跑（进入部署节点检查进程与监听）：

docker compose exec app bash -c 'ss -ltn | grep ":80"; ps aux | grep -E "fcgi|jobber" | grep -v grep | head -4'

LISTEN 0      511          0.0.0.0:80         0.0.0.0:*    users:(("nginx",pid=18787,fd=7))
LISTEN 0      511          0.0.0.0:443        0.0.0.0:*    users:(("nginx",pid=18787,fd=9))
amusewi+       7  0.0  0.0   3940  2928 ?        Ss   10:46   0:00 /bin/bash /usr/bin/amusewiki-jobber
amusewi+      40  1.9  1.2 230276 191472 ?        S    10:46   0:01 /usr/bin/perl /usr/bin/amusewiki-jobber-exec
amusewi+      41  4.0  1.4 268584 229900 ?        Ss   10:46   0:01 perl-fcgi-pm
amusewi+      68  0.3  1.4 279352 233328 ?        S    10:46   0:00 perl-fcgi

nginx 监听 80/443、FCGI 进程管理器与 jobber 作业守护均已就位。

⚠️ 注意：docker compose exec 默认以 amusewiki 用户进入。后文所有 amusewiki <action> 包装命令必须以 root 进入（docker compose exec -u root app ...），因为包装脚本内部要 sudo -u amusewiki 降权执行；以 amusewiki 用户直接运行会报 Sorry, user amusewiki is not allowed to execute '/usr/bin/amusewiki-...' as amusewiki（实测踩坑，见第十一节 Q2）。

4.3 初始化首个站点（create-doc-site）

全新部署时 SQLite 只有空库、没有任何站点。官方镜像提供的初始化入口是 amusewiki create-doc-site——它会部署数据库 schema、克隆官方文档仓库、创建首个站点与 root 用户：

docker compose exec -u root app amusewiki create-doc-site --hostname localhost --username admin --password q1w2e3r4

实测回显（首次运行即暴露残留库问题，完整实录见第十一节 Q1；清库重跑后的成功回显如下）：

[DBICDH] [info] installing version 87
[DBICDH] [info] deploying version 87
[DBICDH] [debug] Running SQL from /usr/share/perl5/AmuseWikiFarm/dbicdh/SQLite/deploy/87/001-auto-__VERSION.sql
[DBICDH] [debug] Running SQL from /usr/share/perl5/AmuseWikiFarm/dbicdh/SQLite/deploy/87/001-auto.sql
[DBICDH] [debug] Adding database version 87
Cloning into '/var/lib/amusewiki/repo/amw'...
fatal: could not read Username for 'https://amusewiki.org': No such device or address
Cloning into '/var/lib/amusewiki/repo/amw'...
fatal: unable to access 'https://github.com/melmothx/amusewiki-site.git/': HTTP/2 stream 1 was not closed cleanly before end of the underlying stream
An stub repository has been created at /var/lib/amusewiki/repo/amw
Summary of the initial setup:

Host: "localhost"
Site ID: "amw"
Root username: "admin"
Root password: "q1w2e3r4"

You should be able to login at http://localhost/login with the above
credentials. This is going to be a dummy site with the documentation.

You can create a new site at http://localhost/admin/sites

schema 部署成功（版本 87，site/title/users 等 46 张表就位），但两个官方文档仓库源在当时的网络下都失败，脚本自动降级为空 stub 仓库——站点建好了但没有内容。补救：删除 stub 仓库、经可用代理重新克隆官方文档仓库，再重建档案（4.4 节）：

docker compose exec -u root app bash -c 'rm -rf /var/lib/amusewiki/repo/amw && sudo -u amusewiki git -c http.proxy=http://192.168.1.72:7897 clone https://github.com/melmothx/amusewiki-site.git /var/lib/amusewiki/repo/amw'

Cloning into '/var/lib/amusewiki/repo/amw'...

docker compose exec -u root app bash -c 'ls /var/lib/amusewiki/repo/amw | head'

a
b
bin
c
f
h
i
l
m
README.md

⚠️ 网络说明：https://github.com/melmothx/amusewiki-site.git 直连失败（Failed to connect to github.com port 443 after 136372 ms: Couldn't connect to server），改用代理 http://192.168.1.72:7897 后克隆成功；https://amusewiki.org/git/amw 当时要求认证（could not read Username），不可用。

4.4 重建站点档案（bootstrap-archive）

站点内容以 git 仓库为准，数据库档案需要重建：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-bootstrap-archive amw'

实测回显（节选）：

Inserting data for /var/lib/amusewiki/repo/amw/u/ub/upstream-bugs.muse
Changing upstream-bugs status from unpublished to published
Updating upstream-bugs in Xapian db
Working on working-with-footnotes.muse file in /var/lib/amusewiki/repo/amw/w/ww
* Created working-with-footnotes.bare.html
* Created working-with-footnotes.html
* Created working-with-footnotes.epub
* Created working-with-footnotes.tex
* Created working-with-footnotes.zip
Inserting data for /var/lib/amusewiki/repo/amw/w/ww/working-with-footnotes.muse
Changing working-with-footnotes status from unpublished to published
Updating working-with-footnotes in Xapian db
Updating title and category sorting
Updated 61 records in 0 seconds
Scheduled static indexes generation

每个 .muse 文档被编译为 HTML/bare HTML/EPUB/TeX/ZIP 多形态产物并入库、进 Xapian 索引。验证库内已发布条目：

docker compose exec -u root app bash -c 'sqlite3 /var/lib/dbconfig-common/sqlite3/amusewiki/amusewiki "select count(*) from title where status=\"published\";"'

4.5 nginx 站点配置

镜像自带一条通配站点 /etc/nginx/sites-enabled/amusewikidebian（server_name localhost，80/443，include amusewikidebian_include），实测文件原文：

server {
    listen 80;
    listen [::]:80;
    listen 443 ssl;
    listen [::]:443 ssl;
    ssl_certificate_key /var/lib/amusewiki/ssl/amusewikidebian.key;
    ssl_certificate     /var/lib/amusewiki/ssl/amusewikidebian.crt;
    server_name localhost;
    access_log /var/log/nginx/localhost.log combined;
    error_log /var/log/nginx/localhost.err.log;
    client_max_body_size 8m;
    include amusewikidebian_include;

}

多站点扩容或改域名后，官方用 amusewiki generate-nginx-conf 生成激活命令（该命令只打印需 root 执行的命令，不直接写文件；单站点默认场景无需执行）：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-generate-nginx-conf'

（本次实测无输出——当前站点由镜像内置通配站点覆盖，无新增激活命令）

4.6 验证服务与出版输出

curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost:8140/
curl -s -o /dev/null -w 'GET /login -> %{http_code}\n' http://localhost:8140/login

GET / -> 401
GET /login -> 200

/ 返回 401 是因为站点默认 private 模式（见第七节）。用 root 账号登录并验证出版产物下载：

docker compose exec -u root app bash -c 'curl -s -c /tmp/cj.txt -o /dev/null -w "POST login: %{http_code} -> %{redirect_url}\n" -d "__auth_user=admin&__auth_pass=q1w2e3r4" http://localhost/login; curl -s -b /tmp/cj.txt -o /tmp/t.epub -w "GET /library/upstream-bugs.epub: %{http_code} %{content_type} %{size_download}B\n" http://localhost/library/upstream-bugs.epub; file /tmp/t.epub'

POST login: 302 -> http://localhost/
GET /library/upstream-bugs.epub: 200 application/epub+zip 6965B
/tmp/t.epub: EPUB document

登录成功（302 跳回首页）、EPUB 下载 200 且 file 识别为合法 EPUB——部署与出版链路全通。

五、数据持久化说明

五个 bind mount 的职责与备份口径（宿主侧目录均位于项目目录 ./data/ 下）：

宿主目录	节点内路径	内容	是否必须持久化
`./data/repo`	`/var/lib/amusewiki/repo`	各站点 git 仓库（内容本体，`.muse` 源文件+元数据）	是
`./data/db`	`/var/lib/dbconfig-common/sqlite3/amusewiki`	SQLite 数据库（站点/用户/档案/权限）	是
`./data/staging`	`/var/lib/amusewiki/staging`	编辑中草稿	建议
`./data/thumbnails`	`/var/lib/amusewiki/thumbnails`	封面/预览缩略图	否（可重建）
`./data/sites`	`/etc/nginx/sites-enabled`	nginx 站点配置（由 generate-nginx-conf 维护）	建议

镜像另声明 OTHER_VOLUMES_USED_IN_CONTAINER=/var/lib/amusewiki/log, /var/lib/amusewiki/ssl, /var/lib/amusewiki/.ssh（日志、证书、仓库推送密钥），生产部署建议一并挂载。

持久化实测：执行 docker compose down 再 docker compose up -d 后，两个站点（见 10.2）与全部档案原样存在，登录、EPUB 下载复验通过：

POST login: 302 -> http://localhost/
GET /login: 200

六、环境变量表

rojen/amusewiki:package 镜像内置默认值（docker inspect 实测）与 compose 覆盖项：

变量	默认值	消费点	说明
`AMW_WORKERS`	`5`	应用启动	FCGI worker 数（官方文档口径默认 3）
`AMW_NPROC`	`5`	`amusewiki-web` 单元 `plackup --nproc`	进程数
`AMW_USERNAME`	`amusewiki`	`/usr/bin/post-password.sh`	初始 root 用户名
`AMW_PASSWORD`	`changeme`	`/usr/bin/post-password.sh`	初始 root 口令
`CHANGE_PASSWORD_BEFORE_RUN`	（未设）	`/usr/bin/post-password.sh`	置 `true` 时按上面两个变量重置口令
`POST_DOMAIN`	（未设）	`/usr/bin/post-domain.sh`	改首个站点 canonical 域名并触发 nginx 重生成
`CHANGE_DOMAIN_BY_ID`	`1`	`/usr/bin/post-domain.sh`	按 rowid 选择要改域名的站点
`AMW_SQLITE_PATH`	`/var/lib/dbconfig-common/sqlite3/amusewiki/amusewiki`	helper 脚本	SQLite 库路径
`NGX_PREFIX`	`amusewikidebian`	nginx 配置命名	实例标识前缀（影响站点文件名）
`CREATE_MISSING_STAGING_FILES`	（未设）	`/usr/bin/create-missing-stating-files.sh`	按日志自动补 staging 占位文件

⚠️ 注意：实测 package 变体的 systemd 单元并不自动调用 post-password.sh/post-domain.sh（grep 单元目录无引用），这两个 helper 是给源码变体/手工初始化用的。初始账号与密码以 4.3 节 create-doc-site --username/--password 参数为准，不要指望环境变量自动建号。

七、配置参数说明

部署后最常动的三处配置（完整参数体系见本专栏《AmuseWiki 2.611 配置参数详解》篇）：

应用主配置 /etc/amusewiki.conf（镜像内置）：<Model::Webserver> 块定义 fcgi_socket、nginx_root、instance_name 等，决定 nginx 配置生成行为。
数据库连接 /var/lib/amusewiki/dbic.yaml：amuse 段的 dsn 指向 SQLite；换 PostgreSQL/MySQL 只改此文件。
站点级配置：存在数据库 site 表（模式 private/public、主题、输出格式开关 tex/pdf/epub/zip 等），命令行改法实测：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-set-site-variable demo --set siteslogan="Demo farm site"'

Updating demo siteslogan => Demo farm site

docker compose exec -u root app bash -c 'sqlite3 /var/lib/dbconfig-common/sqlite3/amusewiki/amusewiki "select id, siteslogan from site where id=\"demo\";"'

demo|Demo farm site

八、配置文件挂载

默认 compose 未挂载应用配置（全部用镜像内置值）。如需自定义，在 volumes 追加只读挂载即可，例如固定 Webserver 模型配置与数据库连接：

    volumes:
      - ./etc/amusewiki.conf:/etc/amusewiki.conf:ro
      - ./etc/dbic.yaml:/var/lib/amusewiki/dbic.yaml:ro

注意 dbic.yaml 属主须为运行用户且权限 0600（官方要求，镜像默认即 -rw------- amusewiki）。nginx 站点目录已默认挂载到 ./data/sites，generate-nginx-conf 的产物会直接落宿主。

九、等价 docker run

docker network create --subnet 10.89.60.0/24 amusewiki-net
docker run -d --name amusewiki-2611-web \
  --hostname amusewiki.local \
  --network amusewiki-net --ip 10.89.60.10 \
  -p 8140:80 \
  -e POST_DOMAIN=localhost \
  -e CHANGE_PASSWORD_BEFORE_RUN=true \
  -e AMW_USERNAME=admin \
  -e AMW_PASSWORD=q1w2e3r4 \
  -e AMW_WORKERS=3 \
  -v $PWD/data/repo:/var/lib/amusewiki/repo \
  -v $PWD/data/thumbnails:/var/lib/amusewiki/thumbnails \
  -v $PWD/data/staging:/var/lib/amusewiki/staging \
  -v $PWD/data/db:/var/lib/dbconfig-common/sqlite3/amusewiki \
  -v $PWD/data/sites:/etc/nginx/sites-enabled \
  rojen/amusewiki:package

十、常用运维命令

10.1 状态与日志

docker compose ps
docker compose logs --tail 20 app
docker compose exec app tail -6 /var/lib/amusewiki/log/amw.log

应用日志实测（jobber 处理静态索引作业的回执）：

2026/11/01 10:46:10 INFO - AmuseWikiFarm.Utils.Jobber - /usr/share/perl5/AmuseWikiFarm/Utils/Jobber.pm:105 - Starting job with pid 87
2026/11/01 10:46:10 INFO - AmuseWikiFarm.Utils.Jobber - /usr/share/perl5/AmuseWikiFarm/Utils/Jobber.pm:67 - Detached new job build_static_indexes 2026-11-01T10:46:10
2026/11/01 10:46:10 INFO - AmuseWikiFarm.Utils.Jobber - /usr/share/perl5/AmuseWikiFarm/Utils/Jobber.pm:116 - job 87 finished, exiting

10.2 多站点农场扩容（clone-site 导出→改→导入）

AmuseWiki 是 wiki 农场：一套实例承载多站点，站点按 canonical 域名路由。CLI 扩容实测（导出首个站点配置作模板）：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-clone-site export --directory /tmp/exported'

Exported site amw to /tmp/exported/amw.yaml

复制 amw.yaml 为 demo.yaml，改三个字段（其余 categories/users/site_options 原样继承）：

canonical: demo.localhost
id: demo
sitename: Demo Library

导入并 bootstrap：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-clone-site import /tmp/exported/demo.yaml --bootstrap'

Please place the site tree into /var/lib/amusewiki/repo/demo at /usr/bin/amusewiki-clone-site line 109.
Importing /tmp/exported/demo.yaml
admin already exists, adding it to the site

10.3 内容导入（git 仓库模型）

新站点要求把内容树放进 repo/<site-id>。站点仓库是 git 库，路径规则是「标题首字母/标题前两字母/文件名」（实测教训见第十一节 Q6）。放入一页并重建档案：

docker compose exec -u root app bash -c 'mkdir -p /var/lib/amusewiki/repo/demo/h/ho && cat > /var/lib/amusewiki/repo/demo/h/ho/hello.muse <<EOF
#title Hello World
#author root
#date 2026-11-01
#publisher Demo Library
#category topic demo

= Welcome

This is a test page created via the git backend of the demo farm site.
EOF
chown -R amusewiki:amusewiki /var/lib/amusewiki/repo/demo && cd /var/lib/amusewiki/repo/demo && sudo -u amusewiki git init -q && sudo -u amusewiki git add -A && sudo -u amusewiki git -c user.email=root@localhost -c user.name=root commit -qm "add hello page"'

a538e6b move to h/ho
f7c5e19 add hello page

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-bootstrap-archive demo'

Processing demo
No language found, assuming english
Custom directives: category, topic demo
Inserting data for /var/lib/amusewiki/repo/demo/h/ho/hello.muse
Updating hello in Xapian db
Updating title and category sorting
Updated 0 records in 0 seconds
Scheduled static indexes generation

验证按域名路由到第二站点（Host 头模拟访问 demo.localhost）：

docker compose exec -u root app bash -c 'curl -s -H "Host: demo.localhost" http://localhost/login | grep -oE "<title>[^<]*</title>"'

<title>Login | Demo Library</title>

docker compose exec -u root app bash -c 'curl -s -c /tmp/dj.txt -o /dev/null -w "POST login: %{http_code} -> %{redirect_url}\n" -H "Host: demo.localhost" -d "__auth_user=admin&__auth_pass=q1w2e3r4" http://localhost/login; curl -s -b /tmp/dj.txt -H "Host: demo.localhost" http://localhost/library/hello | grep -oE "<title>[^<]*</title>"; curl -s -b /tmp/dj.txt -H "Host: demo.localhost" -o /tmp/h.epub -w "hello.epub: %{http_code} %{content_type} %{size_download}B\n" http://localhost/library/hello.epub; file /tmp/h.epub'

POST login: 302 -> http://demo.localhost/
<title>Hello World | Demo Library</title>
hello.epub: 200 application/epub+zip 4006B
/tmp/h.epub: EPUB document

10.4 内容导出（XLSX 书目）

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-export-titles demo /tmp/demo.xlsx && ls -la /tmp/demo.xlsx && file /tmp/demo.xlsx'

-rw-r--r-- 1 amusewiki amusewiki 5831 Nov  1 10:42 /tmp/demo.xlsx
/tmp/demo.xlsx: Microsoft Excel 2007+

（首次运行报缺 Excel::Writer::XLSX 模块，安装 libexcel-writer-xlsx-perl 后成功，见第十一节 Q4。）

10.5 平滑重启

amusewiki 包装器的 restart 动作会先起一个临时 FCGI 实例、切换后再回收，避免停机（脚本逻辑实测见本专栏《AmuseWiki 2.611 常用 CLI 命令与工具详解》篇）：

docker compose exec -u root app amusewiki restart

十一、常见问题

11.1 Q1：create-doc-site 报 `Install not possible as versions table already exists`

现象：[DBICDH] [info] installing version 87 后紧跟 DBIx::Class::DeploymentHandler::Dad::install(): Install not possible as versions table already exists in database at /usr/bin/amusewiki-create-doc-site line 113。
定位：sqlite3 <库> ".tables" 只有 dbix_class_deploymenthandler_versions 一张表、且其中残留一行 1|2||——版本表存在但业务表从未部署，属于半成品库（挂载卷带过来的旧状态）。
解决：全新农场直接删库重跑（数据尚未产生，安全）：

docker compose exec -u root app bash -c 'rm -f /var/lib/dbconfig-common/sqlite3/amusewiki/amusewiki && amusewiki create-doc-site --hostname localhost --username admin --password q1w2e3r4'

重跑后回显出现 deploying version 87 与 46 张业务表即成功。若库中已有真实数据，不可删库，应改用 amusewiki upgrade-db 走增量部署。

11.2 Q2：`amusewiki xxx` 报 `Sorry, user amusewiki is not allowed to execute ... as amusewiki`

现象：进入部署节点直接跑 amusewiki create-doc-site ... 被 sudo 拒绝。
定位：/usr/sbin/amusewiki 包装器设计给 root 使用，内部 sudo -u amusewiki 降权执行并 cd /var/lib/amusewiki；amusewiki 用户再 sudo 成自己不在授权内。
解决：以 root 身份执行包装器（docker compose exec -u root app amusewiki ...），或直接以 amusewiki 用户裸跑 /usr/bin/amusewiki-xxx 并自行 cd /var/lib/amusewiki。

11.3 Q3：文档仓库克隆失败，站点建出来是空 stub

现象：4.3 节回显中 could not read Username for 'https://amusewiki.org' 与 HTTP/2 stream ... not closed cleanly，最后打印 An stub repository has been created。
定位：amusewiki.org/git/amw 匿名 HTTPS 克隆要求认证；github.com 直连超时。
解决：rm -rf repo/amw 后 git -c http.proxy=http://192.168.1.72:7897 clone https://github.com/melmothx/amusewiki-site.git，再 amusewiki bootstrap-archive amw 重建档案（实测 Updated 61 records）。

11.4 Q4：export-titles 报 `Can't locate Excel/Writer/XLSX.pm`

现象：脚本 usage 提示「in debian: libspreadsheet-xlsx-perl」，但装了该包后依旧报错。
定位：libspreadsheet-xlsx-perl 提供的是读取库 Spreadsheet::XLSX；写出 XLSX 的 Excel::Writer::XLSX 对应包名是 libexcel-writer-xlsx-perl——usage 提示的包名是错的。
解决：

docker compose exec -u root app apt-get install -y libexcel-writer-xlsx-perl

Unpacking libexcel-writer-xlsx-perl (1.10-1) ...
Setting up libexcel-writer-xlsx-perl (1.10-1) ...

重跑即生成 Microsoft Excel 2007+ 文件。

11.5 Q5：check-compiler 报 `Command 'xelatex' not found`

现象：Failure to compile ... cs.muse、not ok 1 - cs.pdf exists。
定位：TeX Live 装在 /opt/amusewiki-texlive/current/bin/arch，由 amusewiki-jobber 单元的 Environment=PATH 注入；手工执行时默认 PATH 不含它。
解决：带 PATH 执行：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki env PATH=/opt/amusewiki-texlive/current/bin/arch:/usr/bin:/bin amusewiki-check-compiler'

* Created nl.pdf
ok 1 - /tmp/BVwFWfHTMt/nl.pdf exists
ok 2 - /tmp/BVwFWfHTMt/nl.tex exists

11.6 Q6：bootstrap-archive 报 `Discarding h/he/hello.muse, expected path is h/ho/hello.muse`

定位：站点仓库目录规则为「标题 slug 首字母/前两字母/文件」，hello 应放 h/ho/ 而非 h/he/；放错路径的文件被直接丢弃、不入库。
解决：git mv（注意目录属主须为 amusewiki，root 建的子目录会让 git 报 Permission denied，先 chown -R amusewiki:amusewiki）后重跑 amusewiki bootstrap-archive demo。

11.7 Q7：`GET /` 返回 401

定位：站点 mode 默认 private（site 表实测 amw|private），匿名不可读，属预期行为。
解决：登录后访问；或在管理面板将站点设为公开（注意：amusewiki set-site-variable <site-id> --set mode=public 实测无效——mode 为保留变量，CLI 打印 Updating 后即 die 并回滚事务，详见《AmuseWiki 2.611 常用 CLI 命令与工具详解》 6.1 节）；或按 IP 放行：

docker compose exec -u root app bash -c 'cd /var/lib/amusewiki && sudo -u amusewiki amusewiki-whitelist-ip --site demo --add 10.89.60.1 --list'

Adding 10.89.60.1 to demo
demo 10.89.60.1 root

十二、参考链接

AmuseWiki 官网：https://amusewiki.org/
官方安装文档：https://amusewiki.org/library/install
官方 Debian 仓库（2026-05 起）：https://deb.amusewiki.org/
源码仓库：https://github.com/melmothx/amusewiki
官方文档站点仓库（create-doc-site 克隆源）：https://github.com/melmothx/amusewiki-site
Docker Hub 镜像：https://hub.docker.com/r/rojen/amusewiki
在线演示沙箱：https://sandbox.amusewiki.org/

AmuseWiki Docker Compose 部署指南

AmuseWiki Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 准备项目目录与 compose 文件

4.2 启动栈

4.3 初始化首个站点（create-doc-site）

4.4 重建站点档案（bootstrap-archive）

4.5 nginx 站点配置

4.6 验证服务与出版输出

五、数据持久化说明

六、环境变量表

七、配置参数说明

八、配置文件挂载

九、等价 docker run

十、常用运维命令

10.1 状态与日志

10.2 多站点农场扩容（clone-site 导出→改→导入）

10.3 内容导入（git 仓库模型）

10.4 内容导出（XLSX 书目）

10.5 平滑重启

十一、常见问题

11.1 Q1：create-doc-site 报 Install not possible as versions table already exists

11.2 Q2：amusewiki xxx 报 Sorry, user amusewiki is not allowed to execute ... as amusewiki

11.3 Q3：文档仓库克隆失败，站点建出来是空 stub

11.4 Q4：export-titles 报 Can't locate Excel/Writer/XLSX.pm

11.5 Q5：check-compiler 报 Command 'xelatex' not found

11.6 Q6：bootstrap-archive 报 Discarding h/he/hello.muse, expected path is h/ho/hello.muse

11.7 Q7：GET / 返回 401

十二、参考链接

11.1 Q1：create-doc-site 报 `Install not possible as versions table already exists`

11.2 Q2：`amusewiki xxx` 报 `Sorry, user amusewiki is not allowed to execute ... as amusewiki`

11.4 Q4：export-titles 报 `Can't locate Excel/Writer/XLSX.pm`

11.5 Q5：check-compiler 报 `Command 'xelatex' not found`

11.6 Q6：bootstrap-archive 报 `Discarding h/he/hello.muse, expected path is h/ho/hello.muse`

11.7 Q7：`GET /` 返回 401