部署指南

部署形态怎么选

对外分发的产物为预构建镜像 / 安装包，不依赖源码环境；下载时官网附 SHA256 校验值。数据库两档：SQLite（默认，零运维单文件）与 MySQL 8（多人 / 云端建议），按部署形态选择，桌面安装版可在工具箱中切换。

部署到 Docker（按设备选一条路）

镜像发布在腾讯云公有仓库 ccr.ccs.tencentyun.com/xianmuwork/xianmuims——免登录、免配置，同时提供 x86（amd64）与 ARM（arm64）两种架构——树莓派（64 位系统）走 arm64，已在实机验证。下面几条路都在"下载一个文件 + 一条命令"或"界面点几下"的量级：

一行命令起服务（电脑 / 树莓派 / 云服务器）

已经装好 Docker 的机器，整行复制、粘贴、回车即可（建目录 → 下载启动配置 → 拉镜像启动，一步到位）。

树莓派 / Linux / macOS（终端里执行，一行会自动识别你的 Docker 是新版还是老版本）：

mkdir -p xianmu-ims && cd xianmu-ims && curl -fsSLO https://down.wwzu.com/release/docker/docker-compose.yml && { DC=docker-compose; docker compose version >/dev/null 2>&1 && DC="docker compose"; $DC up -d; }

Windows（已装 Docker Desktop，PowerShell 里执行）：

mkdir xianmu-ims; cd xianmu-ims; iwr https://down.wwzu.com/release/docker/docker-compose.yml -OutFile docker-compose.yml; docker compose up -d

关于 docker compose 与 docker-compose 两种写法：新版 Docker（官方安装脚本、Docker Desktop、群晖较新套件）是 docker compose（空格）；老版本（树莓派上 apt install docker-compose 装的）只有 docker-compose（连字符）。上面那行两种都能跑，直接粘即可；本文其它命令（如升级用的 docker compose pull）在老版本机器上请把空格改成连字符。

Windows 三个提示：① PowerShell 里的 curl 是 Invoke-WebRequest 的别名，不认 -fsSLO 这类参数（报错「找不到与参数名称"fsSLO"匹配的参数」就是它）——所以上面用系统自带的 iwr；一定要用 curl 请写全 curl.exe（Win10 起自带）。② 报错时先看第一条信息，后面的报错通常是它引起的连锁反应。③ 不想敲命令：浏览器直接打开那个 yaml 地址会下载文件，另存为 docker-compose.yml（别存成 .txt）放进该文件夹，再执行 docker compose up -d 即可。

然后浏览器打开 http://主机IP:8066（同一台机器就是 http://127.0.0.1:8066）。这一行做了三件事：建 xianmu-ims 文件夹、下载启动配置、拉镜像并启动；数据都落在该文件夹的 data/ 里，备份＝停容器后整包拷走它。端口被占时把 IMS_PORT=18066 加在最前面（Windows 写 $env:IMS_PORT='18066';），再访问对应端口即可。

群晖 / 威联通 NAS

1. 群晖 DSM：Container Manager →「项目」→ 新增，填项目名（如 xianmu-ims）与路径（如 /volume1/docker/xianmu-ims），来源选「创建 docker-compose.yml」，把下面整段粘进去 →「下一步」→「完成」（首次拉镜像几分钟）；也可以先把 yaml 下载到电脑，来源改选「上传 docker-compose.yml」；
2. 威联通及其它品牌：在自带的容器管理界面里找「从 YAML / compose 创建应用」的入口，粘贴同一段内容（各品牌界面文字不同，认 YAML / compose 字样即可）；
3. 浏览器打开 http://NAS-IP:8066，用 /api/v1/health 验证。

粘贴用的整段配置（与下载的 yaml 内容一致）：

services:
  xianmu-ims:
    image: ccr.ccs.tencentyun.com/xianmuwork/xianmuims:latest   # 浮动标签：升级只 pull 即可，不用改版本号
    container_name: xianmu-ims
    restart: unless-stopped
    ports:
      - "${IMS_PORT:-8066}:8066"     # 端口被占时：IMS_PORT=18066 docker compose up -d
    environment:
      TZ: Asia/Shanghai
      DB_ENGINE: sqlite              # 默认零外部依赖
      DATA_DIR: /app/data
      APP_MODE: ${IMS_APP_MODE:-single}  # 多人改 multi（需专业版权限）
      LICENSE_PUBKEY: S7DiD1hYJIEAQ5BXrK/B2o24fVbjMQy3zrzoGOKOkFU=   # 生产公钥（公开材料），勿改
    volumes:
      - ./data:/app/data             # 全部数据落在此目录；备份=停容器后整包拷走它

要用 MySQL 8 时（数据量大或已有数据库）：按下面「双容器」一节另起一个 mysql:8.4 服务，DB_HOST 填 NAS 自己的局域网 IP（容器里的 127.0.0.1 指容器自身，连不到宿主机上的 MySQL），数据库侧放行容器网段并监听 0.0.0.0。

两个常见坑：① 套件中心装的「MariaDB 10」不可用（缺 ngram），必须自建 MySQL 8；② Web Station 不适用——它只能跑 PHP / 静态站，本应用自带完整 Web 服务，容器起来直接访问 8066 即可，HTTPS 反代走 DSM「登录门户 → 高级 → 反向代理」。

升级：docker compose pull && docker compose up -d（用的是浮动标签 latest，不用改版本号；data/ 不动）。建议在 DSM「任务计划」里把这两条做成一键更新任务。

双容器（MySQL，多人 / 云端）

多人模式或数据量大时，再加一个 MySQL 8 容器：compose 里补一个 mysql:8.4 服务，应用侧改 DB_ENGINE=mysql 并填 DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD。两点硬性注意：

• 必须 MySQL 8.x，不能用 MariaDB——中文全文检索依赖 MySQL 的 ngram 全文解析器，MariaDB 没有，建表与搜索会失败；
• MySQL 端口不要暴露公网，云服务器形态请用反代出 HTTPS。

启动：docker compose up -d。首次启动自动建表与迁移；健康检查访问 /api/v1/health（返回数据库引擎与版本号即正常）。

初始化向导与模式 / 数据库选择

数据库引擎与运行模式由部署配置决定（Docker 环境变量 DB_ENGINE / APP_MODE，桌面安装版在工具箱「服务 → 运行模式与数据库」切换），不在向导中选择。以多人模式运行的全新空库，首次访问 http://主机:8066 会自动进入初始化向导，三步完成：① 欢迎 → ② 创建管理员（设置用户名与密码）→ ③ 完成（创建即登录，向导只在空库出现一次）。单人模式无向导：自动建好内置管理员，免登录直达。

数据库引擎切换不会自动迁移数据：桌面安装版可在工具箱里切换引擎（两侧数据各自保留，可先导出、切库后再批量导入；切换前自动备份 SQLite）；Docker / NAS 形态以环境变量为准，改引擎时按「旧系统全量导出（CSV / JSON）→ 新引擎重新初始化 → 批量导入，附件目录直接拷贝」迁移。

局域网与手机访问

手机、平板、其他电脑与主机同一局域网时，浏览器直接打开 http://主机IP:8066 即可，无需另装前端。几个要点：

• 端口：固定 8066。不要改成 6665–6669、6000 等端口——Chrome / Edge 视其为不安全端口，直接拒绝访问；
• 防火墙：Windows 主机若网络被识别为「公用」，需给 8066 端口加入站规则或改回「专用」网络；
• 单人模式提醒：单人模式无登录，局域网内任何设备都可读写，请勿把主机暴露到不受信网络；
• HTTPS：纯 http://IP 下 PWA 安装与摄像头扫码不可用（浏览器安全上下文限制）。需要完整能力，在路由器 / NAS 反代层配域名 + 证书（源 https://域名 → 目标 http://localhost:8066）。

备份与恢复

自动备份每天 02:00 执行（两引擎行为一致）：SQLite 生成一致性快照 .db、MySQL 走 mysqldump 生成 .sql.gz，附件一并打包，存放在 data/backups/，滚动保留 30 份。该目录可指向 NAS 挂载路径，实现双机容灾。

手动备份两种：设置页随时全量导出（CSV / JSON，永久免费）；或直接停服后整包拷贝 data/ 文件夹——换电脑迁移就是把这个文件夹搬过去。

恢复（以 compose 为例）：

docker compose stop xianmu-ims

# SQLite：用备份快照覆盖
cp data/backups/ims-YYYYMMDD-HHMMSS.db data/ims.db
rm -f data/ims.db-wal data/ims.db-shm

# MySQL：导入快照
gunzip < data/backups/ims-YYYYMMDD-HHMMSS.sql.gz | \
  docker compose exec -T mysql mysql -u用户 -p密码 库名

# 附件按需恢复
tar -xzf data/backups/attachments-YYYYMMDD-HHMMSS.tar.gz -C data/

docker compose start xianmu-ims

恢复启动后系统会自动执行一轮余额重算校验；「彻底离开平台」= 数据库快照 + data/ 附件目录，随时可带走。

升级与回滚

1. 升级前在设置页手动备份一次（应用会强制提示）；
2. Docker：docker compose pull && docker compose up -d（配置用浮动标签 latest，不用改版本号）；Windows：运行新 setup.exe 覆盖安装（data/ 目录自动保留）；
3. 启动时自动执行数据库增量迁移（只增不破，不停机风险低）；
4. 访问 /api/v1/health 与工作台，核对版本号与余额校验通过。

回滚：换回上一版镜像 / 安装包重建即可，data/ 数据卷不动。专业版授权为本地永久验签，升级、回滚、门户状态都不影响已激活实例继续使用。v1.x 内升级免费；v2.0 起的大版本另行付费（老用户优惠价），不升级可继续永久使用 v1.x。

常见问题

• 页面打不开：按顺序查——设备是否同网段 → 主机 8066 是否在监听 → 防火墙 / 网络配置文件（公用网络默认拦入站）→ 端口是否被其他程序占用；
• SQLite 报 database is locked：确认只跑了一个实例（多进程同时写同一库文件导致）；
• 搜索无结果：设置页「重建全文索引」执行一次；
• MySQL 连接数满：检查应用连接池与 MySQL max_connections；
• 提示 docker: 'compose' is not a docker command / docker-compose: command not found：Docker 装法不同，命令写法也不同——新版用 docker compose（空格），老版本（树莓派 apt 装的常见）用 docker-compose（连字符）。上面那条安装命令会自动识别；手动敲其它命令时按你机器上能跑通的那个写；
• Windows 下载配置报「找不到与参数名称"fsSLO"匹配的参数」：PowerShell 把 curl 当成了 Invoke-WebRequest 的别名——改用 iwr <地址> -OutFile docker-compose.yml，或写全 curl.exe -fsSLO <地址>（Win10 起系统自带）；
• 拉取镜像慢：稍后重试或更换网络；服务器没有外网（内网 / 离线环境）：请先联系客服（联系方式见 常见问题），由客服一对一提供交付与激活方案——激活与换机需联网访问一次门户；
• 标签打印不通：打印服务装在浏览器所在电脑（不是 NAS / 服务器），确认 jcPrinterSdk.exe 在运行且 37989 端口监听、打印机开机插 USB（下载打印服务安装包；安装须默认路径 C 盘、先退杀毒软件、勿禁开机自启），详见用户手册 · 标签打印；
• 手机摄像头扫不了码：纯 IP 的 http 访问没有摄像头权限，配 HTTPS 反代或改用手动输入 / 扫码枪；
• 以上仍未解决：提交 Bug 表单（贴上报错原文与截图，无需登录）；购买、激活与授权类问题请联系客服（客服邮箱 kf@wwzu.com）。