版本：v1.1.0（2026-08-15）· 部署包：
mai-2-dingxin-v1.1.0.tar.gz· 数据基线：_db_backup/mai_2_dingxin_20260815.{dump,sql}
本文档覆盖两种场景的完整可执行步骤：
第一部分 · 全新发布：在一台全新机器上从零部署到可访问。
第二部分 · 升级：已有旧版本（v1.0.x）在线运行，升级到 v1.1.0。
核心架构前提（务必先读）：本系统是 Next.js 16 + PostgreSQL 的常驻服务形态。用户内容全部保存在 PostgreSQL 库
mai_2_dingxin（data表 KV +messages表留言）与data/uploads/（上传文件）。升级 = 换码不换数据：只替换代码，数据库与上传目录永远保留。
一、全新发布（从零部署）
0. 前置要求
项 | 要求 |
|---|---|
Node.js | ≥ 22（推荐 22 LTS） |
PostgreSQL | ≥ 18（本数据基线由 PG 18 生成，低于 18 无法恢复） |
磁盘 | ≥ 2GB（含 node_modules 与构建产物） |
准备两个强随机值（用 openssl rand -base64 48 各生成一次）：
ADMIN_JWT_SECRET— 后台登录 JWT 签名密钥SECRET_MASTER_KEY— 静态数据信封加密主密钥（API Key 加密用）
⚠ 这两个值生产必须设置且与数据库备份分开保管。主密钥丢失 = 库内 LLM API Key 无法解密（需后台重填）。
1. 解压部署包
# Linux / 云服务器
mkdir -p /opt/mai-2-dingxin
tar -xzf mai-2-dingxin-v1.1.0.tar.gz -C /opt/mai-2-dingxin
cd /opt/mai-2-dingxin# Windows（Git Bash / WSL）——坑：Git Bash 的 tar 会把 "C:/..." 当远程主机，
# 必须用 /c/... 形式，或先 cd 到包所在目录用相对名
mkdir -p /c/opt/mai-2-dingxin
tar -xzf /c/Users/<你>/mai-2-dingxin-v1.1.0.tar.gz -C /c/opt/mai-2-dingxin
cd /c/opt/mai-2-dingxin解压后顶层应包含：src/ public/ scripts/ docs/ data/uploads/ _db_backup/ .env.example package.json ... 等。
2. 安装依赖
npm ci # 包内含 package-lock.json，可复现；失败则回退 npm install⚠ 构建期需要 devDependencies（tailwindcss / typescript / @tailwindcss/postcss），不要用
--omit=dev。
3. 准备数据库
# 以 postgres 超级用户建库（库名必须为 mai_2_dingxin）
createdb mai_2_dingxin也可用一键脚本自动建库/建角色/授权/建表（自动处理 PG15+ 的 public 模式 42501 权限坑）：
bash export DATABASE_URL='postgresql://user:pass@127.0.0.1:5432/mai_2_dingxin' npm run setup:db # 若需超级用户授权，另设 DB_ROOT_URL 后重跑
4. 恢复数据基线（可选）
全新空站：跳过本步，首次启动会自动建初始管理员（见第 5 步）。
迁移已有内容：恢复 v1.1.0 数据基线（库非空时加
--clean --if-exists）：
export PATH="/path/to/pgclient/bin:$PATH" # 或用系统安装的 pg 客户端
# 方式一（推荐，自定义格式，支持并行/单表）
pg_restore -Fc --clean --if-exists -d mai_2_dingxin _db_backup/mai_2_dingxin_20260815.dump
# 方式二（纯文本 SQL）
psql -d mai_2_dingxin -f _db_backup/mai_2_dingxin_20260815.sql校验：
psql -d mai_2_dingxin -c "\dt"应看到data、messages两张表；data表约 30 行 KV。
5. 配置环境变量
cp .env.example .env
# 编辑 .env，至少填以下项：
# DATABASE_URL=postgresql://user:pass@127.0.0.1:5432/mai_2_dingxin
# ADMIN_JWT_SECRET=<强随机值>
# SECRET_MASTER_KEY=<强随机值>
# ADMIN_USER=admin # 仅全新库首次启动种子初始管理员用，建号后失效
# ADMIN_PASS=<强口令> # 同上
# NEXT_PUBLIC_SITE_URL=https://你的域名 # 决定 canonical / sitemap / llms.txt 的域名凭证单一真相源 = 数据库：
ADMIN_USER/ADMIN_PASS仅在库中一个用户都没有时才用来建初始管理员，写库后即失效；日常登录只认库内 bcrypt 哈希。
6. 构建
NODE_OPTIONS= npm run build # 必须清空 NODE_OPTIONS，否则沙箱 --use-system-ca 会被 Turbopack 拒绝
echo "build exit=$?" # 应为 07. 启动（四选一）
路线 A — launcher（裸机，带受控重启端点）
npm run start:launcher
# 应用 :3000 ；控制端点 127.0.0.1:3001（只绑回环）
# POST 127.0.0.1:3001/_restart → 受控重启 GET /_ping → 探活路线 B — PM2（生产裸机/云服务器推荐）
export ADMIN_JWT_SECRET=... SECRET_MASTER_KEY=... ADMIN_USER=admin ADMIN_PASS=...
pm2 start ecosystem.config.js --env production
pm2 save && pm2 startup
复制路线 C — Docker
cp .env.example .env && vim .env # 填 ADMIN_* / POSTGRES_PASSWORD
mkdir -p data && chown -R 1000:1000 data # data/ 对容器 node 用户可写
docker compose up -d --build路线 D — 宝塔面板（图形界面，非 Docker）
适合已装宝塔的 Linux 服务器，全程在面板里操作。完整逐步说明与排错表见 宝塔面板部署手册-非Docker.md，要点如下：
宝塔「文件」上传部署包到
/www/wwwroot/mai-2-dingxin并解压（替代第 1 步的命令行解压）。软件商店安装「Node.js 版本管理器」，在「版本管理」里确认 Node v22 就绪。
宝塔「终端」进入项目目录构建（每次新开终端都要先让 node 进 PATH）：
bash export PATH=/www/server/nodejs/v22.23.1/bin:$PATH node -v # 确认 v22 npm ci && NODE_OPTIONS= npm run build # 必须完整安装，不要 --omit=devNode 管理器「添加项目」：目录选项目、启动命令
npm run start、端口 3000、Node v22、运行用户www、实例数 1；环境变量填ADMIN_JWT_SECRET/SECRET_MASTER_KEY/ADMIN_USER/ADMIN_PASS/DATABASE_URL（也可在项目根放.env，next start会自动读取）。赋权数据目录（否则上传写不进）：
chown -R www:www data && chmod -R 755 data。站点反向代理到
http://127.0.0.1:3000→ 申请 Let's Encrypt SSL → 开启「强制 HTTPS」；防火墙只放行 22/80/443，不对外暴露 3000 与 PostgreSQL 的 5432。
⚠ 单副本铁律：本版读缓存为进程内 Map，多副本不自动同步。PM2 必须
instances:1/exec_mode:fork，Docker 不设 replicas，宝塔 Node 项目实例数保持 1，严禁 cluster 或多实例，否则数据不一致。
8. 验证
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/ # 首页 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/health # 健康检查 200
curl -s http://localhost:3000/robots.txt # 应含 Host/Sitemap
curl -s http://localhost:3000/llms.txt # 大模型说明文件浏览器打开 /admin/login，用第 5 步的初始管理员登录，确认产品/新闻/上传图片正常。
二、升级（v1.0.x → v1.1.0）
核心原则
换码不换数据：用户内容始终保留在 PostgreSQL 库与 data/uploads/，升级只替换代码与静态资源，库 / data/uploads/ / .env 一律不动。本版有两处数据层变化，其中一处需跑一次迁移脚本（见第 4 步）。
1. 升级前备份（务必，不可跳过）
# 备份数据库（自定义格式，可回滚）
pg_dump --no-owner --no-privileges -Fc -f /backup/mai_2_dingxin_pre_upgrade.dump \
"$DATABASE_URL"
# 备份上传文件
tar -czf /backup/uploads_pre_upgrade.tar.gz data/uploads也可用项目自带四层备份：
npm run backup（或node scripts/backup-db.mjs），落点data/backups/。
2. 替换代码
cd /opt/mai-2-dingxin
# 方式 A：解压新部署包覆盖（推荐）
tar -xzf /path/mai-2-dingxin-v1.1.0.tar.gz -C . --overwrite
# 方式 B：git 拉取新版本
git fetch --tags && git checkout v1.1.0⚠ 保留不动：
data/（含 uploads）、.env、数据库连接串。新包内不含这些，解压覆盖不会破坏它们。 若之前对src/做过本地 hack，升级前先git diff备份自己的改动。
3. 装依赖 + 构建
npm ci # 或 npm install（依赖无新增原生模块）
NODE_OPTIONS= npm run build宝塔部署时，先
export PATH=/www/server/nodejs/v22.23.1/bin:$PATH再执行上面两步（宝塔终端默认无 Node 22）。
4. 数据迁移（v1.0.x 升级必做）
本版数据层有两处变化，处理方式不同：
messages 表新增
type/meta字段（询盘单功能用）：应用启动时会自动ALTER TABLE ... ADD COLUMN IF NOT EXISTS补全，无需手动操作，重启即完成。团队成员拆分为独立模块：v1.0.0 的成员存于
about.json的team[]，v1.1.0 起前台改读独立team.json。需跑一次迁移脚本，否则「核心团队」区块会为空：
bash node scripts/migrate-team.mjs # 幂等：team.json 已有成员则自动跳过；about.json 的 team[] 保留未删，不影响
5. 重启
# launcher 模式
curl -X POST http://127.0.0.1:3001/_restart
# PM2 模式
pm2 restart mai-2-dingxin
# Docker 模式
docker compose up -d --build
# 宝塔模式：Node.js 版本管理器 → 项目 mai-2-dingxin → 「重启」6. 验证 + 数据校验
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/ # 200
curl -s http://localhost:3000/llms.txt | head # 新功能在册登录后台核对：产品/新闻/解决方案/自定义页面/团队成员/工具页等旧数据原样保留（换码不换数据的直接验证）。确认无误后，本版升级完成。
7. 回滚（如升级后异常）
# 换回旧代码
git checkout v1.0.0 # 或解压旧部署包覆盖
NODE_OPTIONS= npm run build
# 重启（同上）
# 若数据被误动，恢复第 1 步备份：
pg_restore -Fc --clean --if-exists -d mai_2_dingxin /backup/mai_2_dingxin_pre_upgrade.dump附：本版（v1.1.0）变更摘要
详见 CHANGELOG.md。关键新增/变更：
暗夜模板统一到后台区块编排（9 个首页区块浅色化 + 补齐缺失区块，顺序/显隐/内容全部后台可控）。
新增：企业微信推送、自定义页面、工具页（原生 + HTML 托管）、团队成员模块、
/llms.txt、首页「关于我们」区块、科技蓝/自然绿 footer 二维码。修复：header logo 图+文字同显、留言未标已读、hero 轮播背景不生效、解决方案区块背景透深色、产品详情图裁剪等。