一、适用范围与约定

1.1关于手册

本手册覆盖内容管理系统与数字平台云主机的应用部署、数据库、站点、调度与备份恢复，是日常运维与故障处理的操作依据。文中命令与界面路径均按服务器当前实际状态编写，可直接照做。

1.2关于敏感信息

本手册不写入任何账号密码、密钥、令牌。凡涉及凭据之处，一律指向实际存放位置：数据库口令在容器环境变量中（docker inspect 可查），应用配置在 /www/data/ruoyi/ruoyi-office/yudao-server/src/main/resources/application-local.yaml，宝塔面板与 SSH 凭据单独保管，不在本手册内。

二、日常巡检

2.1资源水位

2.2重启后检查清单

docker ps 确认三个容器在跑。

ss -tlnp | grep 48080 后端监听（启动约 108 秒，耐心等两分钟）。

ss -tlnp | grep -E '9999|9090' 执行器与调度中心。

curl -s http://127.0.0.1:48080/ -o /dev/null -w '%{http_code}' 返回 401 即正常。

浏览器登录 sys 站，抽查工作台与菜单。

打开内容管理系统首页，确认页面与图片正常。

三、备份与恢复

3.1三层备份体系与现状

备份分三层，一层只管一段，互相不能替代：一层管整台机器，一层管日常误操作，一层管这台机器本身出事。三层缺哪一层，那一段就是完全裸露的。

三层的分界记一句话就够——镜像管「整机没了」，宝塔管「手滑改坏了」，本地管「这台机器本身出事了」。日常小问题多半靠第二层顶住，主机真出事只能靠第一层和第三层。

频率：镜像在大版本上线前打一次、平时每月一次；宝塔是每日自动，不占人工；本地在每次发版时打一次，月末再补一次全量。

每层都要验过才算数：镜像能在控制台以它启动一台临时机器；宝塔看任务日志有产物、体积正常；本地包 gzip -t 通过，再抽一两个文件与线上比对。只打不验，出事那天才发现是空的。

三层之中，第二层已在运行，各项任务、位置与状态见下表；第一层是否已开启自动快照，需登录云主机控制台确认，确认之前按「没有」对待；第三层的做法见 3.6 至 3.9。

3.2PostgreSQL 每日自动备份

3.2.1 为什么不用宝塔的「备份数据库」任务

宝塔的数据库备份任务只认它自己安装或登记过的库。本机 PG16 跑在 Docker 容器里，宝塔「数据库 → Pgsql」页显示的是「当前未安装 PgSql 环境」，只给两个按钮：

〔安装 PgSql 环境〕：会在宿主机再装一套原生 PostgreSQL，与容器抢 5432 端口，数据可能进错库。绝对不能点。

〔远程数据库〕：把容器里的库登记成远程库，面板要校验版本与权限，对容器内数据库支持不可靠，可能登记后仍然备份失败。

结论：因此改用宝塔「计划任务 → Shell脚本」：仍然是面板排期、面板看日志，脚本内部直接进容器跑 pg_dump，不依赖面板的数据库模块，也不受面板升级影响。

3.2.2 任务配置

3.2.3 脚本机制

用 docker exec ruoyi-postgres pg_dump -U "$POSTGRES_USER" -Fc 导出，用户名取自容器环境变量，脚本里不出现任何密码。

先写临时文件 .part，用 pg_restore -l 读一遍目录，确认能读出对象才改成正式文件名，避免半截文件冒充备份。

小于 10KB 一律判定无效，防止空文件显示成功。

任何一项失败即 exit 1，宝塔任务列表会标红，不会再出现“显示成功但没东西”。

保留最近 30 天，自动清理更早的 dump；每次运行追加写入 /www/data/backup/db/backup.log。

3.2.4 验证方法

ls -lh /www/data/backup/db/

# 确认 dump 里确实带数据段（正常应为 8，xxl_job 共 8 张表有数据）
cat /www/data/backup/db/xxl_job_YYYYMMDD.dump | docker exec -i ruoyi-postgres \
    pg_restore -l | grep -c "TABLE DATA"

# 对照库内实际数据量
docker exec ruoyi-postgres psql -U pgsql_mzgy -d xxl_job \
    -tc "select relname||'='||n_live_tup from pg_stat_user_tables order by n_live_tup desc limit 6"

踩坑：pg_restore -l 后面不要写 – 当文件名，某些版本会报 could not open input file "-"；省略文件名走管道即可。

实测基准：pgsql_mzgy 约 1.3MB、xxl_job 约 22KB。xxl_job 体积小是因为该库总共只有 8 行数据，主要体积是表结构，属正常。

3.2.5 失败排查

3.3宝塔自带备份的现状与调整建议

站点备份把 /www/data/ruoyi/frontend 与 yudao-server 的 jar 目录都当成了“站点”在备，其中 yudao-server 那份每份 440MB，保留 3 份就是 1.3GB。jar 本地随时能重新编译，保留 1 份应急即可，建议把该任务的保留份数由 3 改成 1。

MySQL 那条任务每天显示成功，但备份份数为 0，需要进任务日志确认是否真的产出了文件。内容管理系统数据虽然变动少，但没有备份等于裸奔。

宝塔自带的 /www/backup 与业务备份目录 /www/data/backup 是两回事，清理时不要混，也不要把业务备份放错地方。

3.4恢复演练

备份能读出来不等于能恢复进去。建议找时间做一次演练，全程只碰临时库，生产库只读：

docker exec ruoyi-postgres psql -U pgsql_mzgy -c "create database pgsql_mzgy_verify"

cat /www/data/backup/db/pgsql_mzgy_YYYYMMDD.dump | docker exec -i ruoyi-postgres \
    pg_restore -U pgsql_mzgy -d pgsql_mzgy_verify --no-owner 2>&1 | tail -15

docker exec ruoyi-postgres psql -U pgsql_mzgy -d pgsql_mzgy_verify \
    -tc "select count(*) from information_schema.tables where table_schema='public'"

# 表数对上生产库（327 上下）后清理
docker exec ruoyi-postgres psql -U pgsql_mzgy -c "drop database pgsql_mzgy_verify"

恢复演练只在临时库上进行，生产库全程只读。做完一次，“备份可用”才算从推测变成事实。

3.5备份目录规范

上传文件、备份产物一律放 /www/data/backup/，不散落在业务目录里。

命名带日期：数据库 dump 用 库名_YYYYMMDD.dump；jar 用 yudao-server-YYYYMMDD-HHMM.jar；全量备份用目录 mzgy-full-YYYYMMDD-HHMM。

业务目录 /www/data/ruoyi 下不要长期堆放前端历史版本目录，需要留档就压缩后移入 backup，否则过几个月分不清哪个是线上。

3.6本地归档：一个日期一套，两个系统

服务器上的每日备份只能防误删，防不了主机失联——备份和站点在同一块盘上。因此在服务器之外再建一套本地归档：每次发版或月度盘点，把两个系统各取一份完整包，按日期存放，出事时整套拿走就能还原。

目录结构固定为「日期 → 两个系统 → 固定子目录」，一个日期目录就是一次全量，里面不再按版本细分。每个位置放什么、从哪里取，见下表。

四条规矩。一是源码那两格只能从本地工程打包，服务器上没有源码，取不到；二是统一用 tar.gz，不用 zip，zip 在 Windows 下按 cp936 记文件名，拿到 Linux 解包中文目录会变乱码；三是应用配置（application*.yaml、logback-spring.xml）全部打包在 yudao-server.jar 内，服务器上没有外部配置文件，备份了 jar 就等于备份了配置，不要单独拆出来；四是每个系统都要有一份 MANIFEST.txt，记文件名、大小、MD5、来源路径和构建信息，没有它，半年后没人分得清哪个 jar 对应哪次提交。

旧目录 20261003 是 10 月 3 日发版前的快照，按旧命名存放，不迁移、不再往里加内容，只作回退点保留。

本地误删的编译产物先别急着重编译，去回收站找回来再说——这次发版用的那份 18:11 产物，就是从 H 盘回收站里捞回来的。产物归档一律带时间戳，例如 web-antd-dist_20261025_181101.zip，与 dist.zip 共存，避免新旧两个同名包互相覆盖；也不要为了图省事把归档改回 dist.zip。

3.7一次备份怎么做

顺序不要调：前五步在服务器上取数，第六步在本地，最后两步做核对与归档。

取完先别收工，确认两件事：jar 和 dist 是不是这次真要上的那一版（对 commit 与构建时间）；dump 是不是完整的（pg_restore -l 能读出对象目录，体积也不是几 KB）。

3.8恢复怎么做

顺序不能颠倒：先环境、再配置、再产物、最后数据。产物先上而配置后到，服务一定起不来，日志里报的是找不到配置或数据源，很容易误判成代码问题。

验收六条：后端进程在且日志无启动异常；curl 请求 /admin-api 正常返回；前端首页打开不白屏；能登录；左侧菜单树不缺项；内容管理系统首页与后台都能进。缺一条就是没恢复完。

第 4 步必须「先清空再解压」。前端目录里残留旧 hash 文件时，页面会去请求已删除的 chunk，表现是白屏或一直转圈，看着像代码坏了，其实只是没清干净。

3.9保留与异地

只保留最近 3 次全量，加每月末 1 次长期归档，其余删掉。一次约 700MB（其中后端与调度两个 jar 占 590MB），全留一年就是几十 GB，翻找的时间成本比硬盘贵。

H 盘和源机同处一地，至少再放一份到移动硬盘或对象存储。备份与主机同时消失的场景并不罕见，不异地的备份等于没有备份。

四、安全加固

4.1加固内容

4.2加固验收

加固完扫了一遍：0 紧急、0 高风险。所有改动都留了 .bak，能逐项回滚。

五、权限与租户维护

完整方案见《明珠果苑权限模型落地方案》。核心原则一句话：上下级关系用部门树加数据权限，平级隔离用租户。租户管隔离，层级归业务树。

5.1六分类租户

租户编号（tenant_id）不能改，全库几十张表引用它，改动等于级联灾难。

渠道体系（一、二、三级）用系统租户内的部门树加数据权限「本部门及以下」实现，线上、线下用部门命名标识（如「线上·××」「线下·××」）。

基地、伙伴各建一个租户；游客与 C 端用会员体系，不建租户、不进后台。

5.2角色体系

内置角色界面拒绝编辑，需直接改库；只改 name 与 sort，code 一律保留（框架识别用）。

超管账号 yanghsia（昵称杨夏，id=1），日常管理用此号。

5.3跨租户机制

链路为：前端租户切换组件携带 visit-tenant-id 请求头 → 后端 TenantVisitContextInterceptor 校验 → 放行超管跨租户查询。菜单 5010（system:tenant:visit）是入口。

注意：layouts/basic.vue 中的租户切换组件必须保持渲染，不得加 v-if 之类的限制，否则顶栏「请选择租户」下拉会消失。

5.4菜单授权规则与一次越权复盘

先分清：目录（type=1）是子菜单的容器，菜单（type=2）是页面，按钮（type=3）是页面里的操作。三者串起来才是一条可见的授权路径。

规则一：目录节点必须随子菜单一起授予。只给子菜单、不给它上面的目录，前端拿不到父节点，子菜单根本不显示，看起来像授权没生效。要整棵排除用递归条件，例如 m.id <> 1224 即排除「租户管理」及其全部子节点。

规则二：按最小必要给。角色只挂该岗位真用得上的目录与菜单；按钮只给查询类权限码（query、get、list、monitor、preview），增、删、改、导入、导出一律不给；数据权限上，本部门岗位给「本部门及以下」，别图省事给全部。

复盘：渠道账号（system_users id=143，tenant_id=123）曾绑到租户管理员角色 156，该角色挂了 257 个菜单，等于平台全量，渠道登录后因此看得到明珠果苑租户的信息。处置：把角色 156 的「1224 租户管理」及其子树（1138、1139–1143、5010）取消授权，渠道就看不到了。

复查：新增渠道、伙伴账号后，先看它绑的角色有多少条菜单授权，接近全量的立刻警觉。按角色统计条数，第一名最可疑：SELECT role_id, COUNT(*) FROM system_role_menu GROUP BY role_id ORDER BY 2 DESC;

六、内容管理系统运维与安全

6.1安全观察与建议

内容管理系统访问日志每天增长约 20MB，几乎全部是扫描：ThinkPHP、Magento、Symfony 漏洞探测，后门文件探测，AI Agent 协议扫描（/.well-known/*），以及 referrer 为垃圾站点的请求。日志里返回的都是 Primary script unknown 或 not found，说明这些攻击没有成功，我们用的是 PHP + WordPress，与它们打的技术栈不匹配。

建议在宝塔「网站防火墙」里开启 WAF，让扫描在 nginx 之前就被挡掉，既省 CPU 也省日志。不要手写一堆 nginx 拦截规则，升级或换机容易丢。

四个域名打开的是同一份内容。主域为 www.mzgarden.com，www.明珠果苑.com、www.明珠果苑.中国、www.明珠果苑.网址 建议 301 到主域，避免搜索引擎视为重复站点。

注意：主题 functions.php 中同名函数只能定义一次，重复声明会触发 Cannot redeclare 致命错误，改主题后要用无痕窗口验证。现行代码只有一处定义。

6.2内容管理系统改版与素材规范

背景音乐：浏览器一律禁止自动播放，只能由用户点击开启。页面上要留一个明确的开启入口，不要指望进场自动响，否则音乐永远放不出来。

Hero 图：上线前必须压缩，WebP 最佳，单张不超过 300KB。超了首页首屏会明显拖慢，手机端尤其吃亏。

动画性能：水滴类装饰动画控制在 14 个以内，手机端按屏宽缩小尺寸；系统里开了「减少动画」的用户要整组关掉动画（prefers-reduced-motion），别让装饰拖慢首屏。

顶部导航不再靠「外观 → 菜单」手工维护：主题按分类目录树自动生成菜单，后台新建分类、前台自动多一项，排序按分类建立顺序，未分类不显示。分类简介写在分类描述里，会显示在前台分类页。要调整顺序就调分类的顺序或层级，不要回外观里再搭一套静态菜单，两套同时存在会互相打架。

6.3维护模式日常运维

维护模式由自制插件「明珠果苑维护模式 mzgy-maintenance」提供，用于整站升级、改版期间给未登录访客显示一个友好的临时页面，而不是报错或白屏。开关在后台「设置 → 明珠果苑维护」，一个勾选框，状态存于选项 mzgy_maintenance_active。

勾上后，未登录访客访问任意前台页面统一返回 503（带 Retry-After: 3600 头，提示搜索引擎稍后再来，不会误判为宕机）并显示维护页；已登录管理员照常浏览前台。后台、登录页、REST 接口始终放行，所以勾了维护也能正常登录、进后台。管理员顶栏会出现红色「维护模式：已开启」标记，防止忘关。

维护页有两个候选模板，靠重命名切换、不是复制覆盖。插件目录 /www/wwwroot/明珠果苑.com/wp-content/plugins/mzgy-maintenance/ 下：

插件实际加载的是同目录的 maintenance.php。把哪个候选文件名前的中文前缀去掉、重命名为 maintenance.php，前台就显示哪个；两个候选文件都长期保留在目录里，谁叫 maintenance.php 谁生效。同目录只能有一个 maintenance.php，是重命名切换，不要复制覆盖。

日常操作按下面的顺序：

开维护后自检四条：无痕窗口（未登录）打开前台，应看到维护页且 HTTP 状态为 503；登录管理员后打开前台，应正常看到网站而不是维护页；后台、登录页、接口可正常访问；维护结束后顶栏红标消失、无痕窗口恢复正常。

先分清 503 和 403，别误判。整站对未登录访客返维护页、状态码 503，是维护模式在生效；只有单篇文章对游客返 403、登录后能看，是内容卫士 mzgy-guard 的阅读权限控制（见开发手册 4.4），不是维护模式。核对维护中的内容时，用接口取 content.raw 或登录管理员看，不要用游客前台判断。

维护页是纯 HTML、无外部依赖，单独显示不会因样式或资源加载失败而变形。改了主文件 mzgy-maintenance.php 的逻辑后，必要时在后台「插件」页停用再启用一次。不要让静态 index.html 维护页与本插件两套机制并存（见开发手册 4.5）。

七、故障排查

7.1常见故障速查

7.2后端类

7.3前端类

先分诊：无痕窗口打开正常、地址栏手输完整网址回车也正常，说明服务器上只有一个版本，是浏览器本地把旧页面留住了；若两种方式都仍是旧版，先回上面的表查服务器，不要动浏览器。

为了能实时观看修改后的效果，避免页面缓存造成旧版样式驻留，Edge 需按下面三条调整。

三条对应的开关位置：设置 → 起始、主页和新建标签页 → “启动时”选“打开新标签页”；设置 → 系统和性能 → 关掉“启动增强”与“关闭 Microsoft Edge 后继续运行后台扩展和应用”。

普通用户无需处理：输入网址、点链接、从收藏夹进入都属于正常导航，no-cache 会自动取到最新版；即便极端情况下恢复了登录页快照，也只看一次，登录跳转或刷新即自动更新。

7.4数据库类

7.5站点与磁盘类

附录 APostgreSQL 每日备份脚本全文

脚本存档在 H:\系统备忘\常用\备份命令\mzgy-pg-backup-daily.sh，服务器上的执行副本存放在宝塔计划任务「备份PostgreSQL数据库」的脚本框内。迁移或重建时，把下面全文粘贴到「计划任务 → 添加任务 → Shell脚本」即可，无需修改任何变量。

#!/bin/bash
# ============================================================
# 明珠果苑网站 — PostgreSQL 每日备份
# 容器 ruoyi-postgres (postgres:16)，库：pgsql_mzgy、xxl_job
# 用途：粘贴到宝塔「计划任务 → Shell脚本」，每天 02:30 执行
# 2026-10-23 建立
# ============================================================

export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

CONTAINER="ruoyi-postgres"
OUT="/www/data/backup/db"
DBS="pgsql_mzgy xxl_job"
KEEP_DAYS=30
TODAY=$(date +%Y%m%d)
LOG="$OUT/backup.log"

mkdir -p "$OUT"

log() { echo "[$(date '+%F %T')] $*" | tee -a "$LOG"; }

# 取容器内默认超级用户名，不写死、不落密码
PGUSER=$(docker exec "$CONTAINER" printenv POSTGRES_USER 2>/dev/null)
if [ -z "$PGUSER" ]; then
  log "失败：取不到 $CONTAINER 的 POSTGRES_USER，容器可能在重启"
  exit 1
fi

fail=0

for db in $DBS; do
  final="$OUT/${db}_${TODAY}.dump"
  part="$final.part"

  if ! docker exec "$CONTAINER" pg_dump -U "$PGUSER" -Fc -d "$db" > "$part" 2>>"$LOG"; then
    log "失败：$db 导出出错（详见上方 pg_dump 报错）"
    rm -f "$part"
    fail=1
    continue
  fi

  size=$(stat -c %s "$part" 2>/dev/null || echo 0)

  # 校验质量：文件不能太小，且目录（TOC）必须能被 pg_restore 读出
  if [ "$size" -lt 10240 ]; then
    log "失败：$db 备份只有 ${size} 字节，判定为无效"
    rm -f "$part"
    fail=1
    continue
  fi

  if ! docker exec -i "$CONTAINER" pg_restore -l < "$part" > /dev/null 2>>"$LOG"; then
    log "失败：$db 备份文件损坏，pg_restore 无法读取目录"
    rm -f "$part"
    fail=1
    continue
  fi

  mv -f "$part" "$final"
  chmod 600 "$final"
  log "成功：$db  $(du -h "$final" | cut -f1)  $final"
done

# 清理超过保留期的备份
find "$OUT" -maxdepth 1 -type f -name '*.dump' -mtime +"$KEEP_DAYS" | while read -r old; do
  rm -f "$old"
  log "清理：$old"
done

if [ "$fail" -ne 0 ]; then
  log "本次备份有失败项，请检查"
  exit 1
fi

log "两个库全部备份成功，当前目录占用 $(du -sh "$OUT" | cut -f1)"
exit 0

脚本里有两处容易被误改：KEEP_DAYS 是保留天数（改小会提前删历史备份）；DBS 是库名列表，用空格分隔，增减库只需改这一行。

全文完