部署指南

闲沐 IMS 跑在你自己的机器上：个人用装 Windows，全家 / 团队共用部署到 NAS（Docker）。不管哪种形态，数据都落在你自己的数据库与磁盘里，断网照常用。

适用版本：v1.0.0（Windows 安装版随 v1.1.0 发布）｜全部形态统一使用 8066 端口

部署形态怎么选

形态	适合谁	状态
在线演示	先看看再说，零安装	直接访问，数据每日重置
Windows 安装版	个人电脑，双击安装即用（含常驻工具箱）	安装包就绪
Docker / NAS	群晖、QNAP、任意 Docker 环境；多人共用	可用，预构建镜像交付

对外分发的产物为预构建镜像 / 安装包，不依赖源码环境；下载时官网附 SHA256 校验值。数据库两档：SQLite（默认，零运维单文件）与 MySQL 8（多人 / 云端建议），初始化时选择。

Docker / docker-compose

单容器（SQLite，推荐起步）

一个容器搞定全部，data/ 目录就是全部资产（数据库、附件、备份）：

services:
  xianmu-ims:
    image: xianmu-ims:latest
    container_name: xianmu-ims
    restart: unless-stopped
    ports:
      - "8066:8066"          # 局域网访问 http://nas-ip:8066
    environment:
      - TZ=Asia/Shanghai
      - DB_ENGINE=sqlite     # 默认，可省略
      - DATA_DIR=/app/data
      - APP_MODE=single      # 多人改 multi（需专业版权限）
    volumes:
      - ./data:/app/data

双容器（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（返回数据库引擎与版本号即正常）。

群晖 NAS 部署

以群晖 DSM 的 Container Manager 为例（QNAP 及其他 Docker 环境同理）：

把拿到的部署包上传到 NAS（如 /volume1/docker/xianmu-ims/），内含镜像、docker-compose.yml 与说明；
编辑 compose：DB_HOST 填 NAS 自己的局域网 IP（容器里的 127.0.0.1 指容器自身，连不到宿主机上的 MySQL）、数据库账号密码、APP_MODE；
数据库侧放行：连接用户的 Host 允许容器网段（或 %），MySQL 监听 0.0.0.0，DSM 防火墙放行端口；
Container Manager → 项目 → 新增，路径选该文件夹，构建并启动（首次拉取 / 加载镜像几分钟）；
浏览器打开 http://NAS-IP:8066，用 /api/v1/health 验证。

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

建议在 DSM「任务计划」里建一个一键更新任务（docker compose up -d），以后升级就是导入新镜像 + 运行任务两步。

初始化向导

首次访问 http://主机:8066 自动进入向导，三步：① 选数据库（SQLite 默认；MySQL 填连接信息并可测试连接）→ ② 选模式（单人 / 多人，创建管理员账号）→ ③ 完成（自动建表）。Docker 可用环境变量预置（DB_ENGINE 等）跳过向导直接启动。

数据库引擎初始化后不支持在线切换；迁移路径 = 旧系统全量导出（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-HHMM.db data/ims.db
rm -f data/ims.db-wal data/ims.db-shm

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

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

docker compose start xianmu-ims

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

升级与回滚

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

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

常见问题

页面打不开：按顺序查——设备是否同网段 → 主机 8066 是否在监听 → 防火墙 / 网络配置文件（公用网络默认拦入站）→ 端口是否被其他程序占用；
SQLite 报 database is locked：确认只跑了一个实例（多进程同时写同一库文件导致）；
搜索无结果：设置页「重建全文索引」执行一次；
MySQL 连接数满：检查应用连接池与 MySQL max_connections；
标签打印不通：打印服务装在浏览器所在电脑（不是 NAS / 服务器），确认 jcPrinterSdk.exe 在运行且 37989 端口监听、打印机开机插 USB，详见用户手册 · 标签打印；
手机摄像头扫不了码：纯 IP 的 http 访问没有摄像头权限，配 HTTPS 反代或改用手动输入 / 扫码枪；
以上仍未解决：服务 QQ 7740840，购买用户邮箱 kf@wwzu.com（12 个月内安装 / 激活 / 故障类支持）。