收紧文档入口并更新部署真相

README.md

@@ -213,20 +213,25 @@ docker compose -f docker-compose.prod.yml up -d
 
 ## 10. 文档入口
 
-优先阅读：
+主入口优先看：
 
 - `docs/README.md`
 - `docs/deployment/部署说明.md`
 - `docs/deployment/多品牌 NAS 与 Linux 交付差异清单.md`
 - `docs/初次部署与出厂设置指南.md`
-- `docs/客户首装升级坑位排查_20260530.md`
 - `docs/许可证服务接入说明.md`
-- `docs/商业化地基8项收口记录_20260530.md`
 - `docs/参考源码功能吸收整理_20260513.md`
 - `scripts/README.md`
 
+需要追排障、历史收口或版本差异时，再看：
+
+- `docs/客户首装升级坑位排查_20260530.md`
+- `docs/商业化地基8项收口记录_20260530.md`
+- `docs/商业化地基排查问题清单_20260524.md`
+- `docs/许可证链路安全评估_20260312.md`
+
 原则：
 
-- 当前项目事实以当前代码、配置、部署文件和这些入口文档为准。
-- 旧部署记录、一次性排障报告、旧交接文档和历史总结不作为当前事实来源。
+- 当前项目事实以当前代码、配置、部署文件和主入口文档为准。
+- 阶段记录、旧排障报告、旧交接文档和历史总结不作为默认事实来源。
 - 参考源码只用于查思路和做功能吸收判断，不直接参与当前项目运行链路。

docs/README.md

@@ -19,8 +19,6 @@
   面向不同 NAS / Linux 客户现场的部署前采集清单。
 - `初次部署与出厂设置指南.md`
   从零安装、系统初始化和恢复出厂流程。
-- `客户首装升级坑位排查_20260530.md`
-  客户真实首装、升级、回滚、许可证服务和对象存储的当前坑位清单。
 - `新手用户上手指引.md`
   给普通使用者看的基础操作指引。
 
@@ -45,9 +43,11 @@
 - `参考源码功能吸收整理_20260513.md`
   只在需要核对旧参考源码能力边界时阅读；它不是当前产品功能清单，也不是搬旧功能的依据。
 - `商业化地基排查问题清单_20260524.md`
-  内部整改跟踪清单，混有已完成项、待整改项和审计痕迹；只在追问题和核对状态时查看，不作为部署、接入或普通使用手册。
+  内部历史整改台账，混有已完成项、待整改项和审计痕迹；只在追问题和核对状态时查看，不作为部署、接入或普通使用手册。
 - `商业化地基8项收口记录_20260530.md`
-  本轮按商业化私有交付目标收口的 8 项事实记录，作为后续继续推进的短入口。
+  本轮按商业化私有交付目标收口的 8 项阶段记录，只在回看本轮收口时查看，不作为默认入口。
+- `客户首装升级坑位排查_20260530.md`
+  客户首装、升级、回滚、许可证服务和对象存储的历史排障记录，已被更新验证覆盖，默认看部署说明即可。
 - `许可证链路安全评估_20260312.md`
   历史安全评估快照，部分条目已被后续代码和部署配置修正；保留作溯源参考，不作为当前整改入口，引用前必须按当前代码重新复核。
 

docs/deployment/部署说明.md

@@ -107,10 +107,11 @@ NAS 或 Linux 服务器上建议提前准备挂载目录：
 
 ```bash
 mkdir -p uploads data
+chown -R 1001:1001 uploads data
 chmod 775 uploads data
 ```
 
-如果客户系统启用了更严格的用户权限，需让运行主应用容器的用户可以写入这两个目录；当前镜像内应用用户通常按 UID `1001` 理解。最简单的验收标准是：容器启动后能上传素材，`uploads/` 和 `data/` 没有持续出现权限拒绝日志。
+如果客户系统启用了更严格的用户权限，需让运行主应用容器的用户可以写入这两个目录；当前镜像内应用用户通常按 UID `1001` 理解。飞牛 / NAS 场景里，第一次手工创建目录如果是 root 所有权，单纯 `chmod 775` 可能还是不够，优先把目录属主改成 `1001:1001`。最简单的验收标准是：容器启动后能上传素材，`uploads/` 和 `data/` 没有持续出现权限拒绝日志。
 
 ### 2.3 HTTP Registry 前置检查
 

docs/其他项目接入许可证系统说明.md

@@ -543,7 +543,7 @@ LICENSE_PROJECT_CODE=your-project-code
 LICENSE_REQUEST_SIGNING_SECRET=shared-secret-at-least-32-chars
 ```
 
-这两个值不一定非要写在 `.env` 里，也可以放在：
+这三个值不一定非要写在 `.env` 里，也可以放在：
 
 - 系统环境变量
 - 项目配置文件

docs/商业化地基8项收口记录_20260530.md

@@ -2,7 +2,7 @@
 
 更新时间：2026-05-30
 
-本文件记录本轮按“商业化私有交付”目标推进的 8 项地基工作。它不是销售文案，也不是旧参考源码搬运清单；本文档只是 2026-05-30 的阶段快照，后续判断以当前代码、配置和部署文件为准。
+本文件记录本轮按“商业化私有交付”目标推进的 8 项地基工作。它不是销售文案，也不是旧参考源码搬运清单；本文档只是 2026-05-30 的阶段快照，不是默认入口，后续判断以当前代码、配置和部署文件为准。
 
 ## 1. 客户安装和升级演练
 
@@ -134,6 +134,6 @@
 - 文档继续保留旧测试服务器不可作为事实来源的提示。
 - 后续前端浏览器验收前，必须先确认本机数据库和对象存储已恢复。
 
-仍不能假装完成：
+本轮补充：
 
-- 当前没有在飞牛虚拟机或本机 Docker 里完成一轮完整客户安装验收；这仍是下一轮部署演练任务。
+- 当前已在飞牛虚拟机里完成首装、初始化、免费版激活、上传、备份和恢复验收；后续任务转为继续收紧部署说明、权限口径和升级脚本。

docs/商业化地基排查问题清单_20260524.md

@@ -2,7 +2,7 @@
 
 更新时间：2026-05-30
 
-本文件是当前项目面向企业/团队私有化交付前的地基排查记录。它不是对外销售文案，也不是旧参考源码功能吸收清单，而是后续整改的事实入口。它是内部整改跟踪记录，已修复、已完成和待整改条目会同时保留，阅读时必须先看每条状态，不能把整份文件理解成纯待办清单。
+本文件是当前项目面向企业/团队私有化交付前的历史整改台账。它不是对外销售文案，也不是旧参考源码功能吸收清单，更不是当前默认事实入口。已修复、已完成和待整改条目会同时保留，阅读时必须先看每条状态，不能把整份文件理解成纯待办清单。
 
 本次排查以当前仓库代码、配置、部署文件和现存文档为准。`gongxiangp2-source-reference-old-style-20260513-132942` 只作为只读参考目录，本次没有把旧项目 UI 或旧功能直接作为目标。
 

docs/客户首装升级坑位排查_20260530.md

@@ -2,7 +2,7 @@
 
 更新时间：2026-05-30
 
-本文件记录本轮针对客户真实首装、升级、回滚、许可证服务、对象存储和文档真相的排查与修复状态。它是 2026-05-30 的阶段记录，后续仍以当前代码、配置和实际验证结果为准。
+本文件记录本轮针对客户真实首装、升级、回滚、许可证服务、对象存储和文档真相的排查与修复状态。它是 2026-05-30 的阶段记录，后续仍以当前代码、配置和实际验证结果为准。当前飞牛 VM 已完成首装、初始化、免费版激活、上传、备份和恢复验收，本文件后续只保留历史坑位和已修项，不再把“还没跑通”当当前事实。
 
 ## 1. 结论
 

docs/当前工作流.md

@@ -63,11 +63,8 @@ npm run check
 
 - 本地 Compose：`docker compose -f docker-compose.prod.yml up -d`
 - 当前主发布脚本：`deploy-registry.ps1`
-- 旧主应用远程部署脚本：`deploy-new-fixed.ps1`（仅作内部维护参考）
-- 许可证服务部署：`license-server/deploy.ps1`（只在维护 license-server 时使用）
-- 综合发布：`发布管理.ps1`（内部留存）
 
-当前客户交付和升级优先按版本化 Registry 发布链路走，不再默认把旧远程部署脚本当主线。
+当前客户交付和升级优先按版本化 Registry 发布链路走。旧主应用远程部署脚本、综合发布脚本和许可证服务部署脚本都属于内部维护参考，不是当前客户主线。
 
 部署后至少验证：
 

docs/许可证服务接入说明.md

@@ -10,6 +10,8 @@
 LICENSE_SERVER_URL=https://your-license-server.example.com
 LICENSE_PROJECT_CODE=flnxi-sucai
 LICENSE_REQUEST_SIGNING_SECRET=replace-with-same-secret-on-license-server
+LICENSE_PUBLIC_KEY=<license-server-rsa-public-key>
+LOCAL_ENCRYPTION_KEY=<generate-a-32-char-or-longer-local-key>
 ```
 
 含义：
@@ -20,6 +22,10 @@ LICENSE_REQUEST_SIGNING_SECRET=replace-with-same-secret-on-license-server
   当前主应用所属项目编码，必须和 `license-server` 主库中的 `projects.code` 一致
 - `LICENSE_REQUEST_SIGNING_SECRET`
   主应用和许可证服务共享的 HMAC 签名密钥，至少 32 字符，两边必须一致；不要写入 Git 或对外文档
+- `LICENSE_PUBLIC_KEY`
+  许可证服务签发许可证时使用的 RSA 公钥，主应用本地验签和缓存恢复会用到
+- `LOCAL_ENCRYPTION_KEY`
+  主应用本地加密保存许可证缓存时使用的密钥，至少 32 字符，不能使用示例值
 
 Node Agent 如果需要版本检查，也必须配置同样两项：
 
@@ -140,8 +146,8 @@ ${LICENSE_SERVER_URL}/api/license/${LICENSE_PROJECT_CODE}/...
 
 1. `license-server` 主库里已存在目标项目，且 `projects.code = LICENSE_PROJECT_CODE`
 2. 该项目对应的项目库连接配置正确
-3. 主应用 `.env` 已配置 `LICENSE_SERVER_URL`、`LICENSE_PROJECT_CODE` 和 `LICENSE_REQUEST_SIGNING_SECRET`
-4. Node Agent 如启用版本检查，也已配置相同的两项
+3. 主应用 `.env` 已配置 `LICENSE_SERVER_URL`、`LICENSE_PROJECT_CODE`、`LICENSE_REQUEST_SIGNING_SECRET`、`LICENSE_PUBLIC_KEY` 和 `LOCAL_ENCRYPTION_KEY`
+4. Node Agent 如启用版本检查，也已配置相同的远端通信两项
 5. 不再调用任何旧的无项目公开接口
 
 ## 7. 推荐联调方式

scripts/README.md

@@ -31,22 +31,20 @@ npm run migrate:template-data
 npm run verify:template-data
 ```
 
-## 二、当前保留的手动脚本
+## 二、当前客户/实施可用脚本
 
 ### 构建相关
 
-- `build-material-image.ps1`
-  构建主应用镜像。它属于历史/内部维护备用入口，保留旧的测试/正式分层规则，但仍带 Harbor / `latest` 旧口径；客户正式交付、升级、回滚优先用根目录的 `deploy-registry.ps1`，不要把它当成客户升级主线。若确需用它推送旧 Harbor，必须显式追加 `-AcknowledgeLegacyHarborPush`。
 - `build-obfuscated.js`
   生产构建后的服务端混淆处理。客户交付镜像通过 `Dockerfile` 执行 `npm run build:prod` 时会自动调用；混淆依赖或配置缺失会直接失败，不能静默跳过。
 - `docker-entrypoint.sh`
   主应用容器启动入口
-- `generate-shared-test-env.ps1`
-  为共享测试机生成隔离后的 `.env`，避免容器名、卷名、网络名与其他项目冲突
 - `smoke-install.ps1`
   客户首装后的基础验收脚本，可检查 Compose 配置、容器状态、运行镜像、版本文件、迁移状态、MinIO bucket 和 `/api/health`
 - `backup-restore.ps1`
   客户环境备份、恢复和健康验收脚本；恢复必须显式输入确认短语，避免误覆盖客户数据
+- `generate-shared-test-env.ps1`
+  为共享测试机生成隔离后的 `.env`，避免容器名、卷名、网络名与其他项目冲突；这是内部测试脚本，不是客户安装器
 
 ### 数据检查/修复相关
 
@@ -66,8 +64,8 @@ npm run verify:template-data
 1. 能通过 `package.json` 跑的，优先不要手敲文件路径。
 2. 手动脚本通常带环境假设，执行前先读内容。
 3. 带固定服务器地址、固定账号、一次性交付信息的脚本，不应继续当成通用入口。
-4. `build-material-image.ps1` 和 `generate-shared-test-env.ps1` 都偏内部维护，客户交付只在确实需要时使用。
-5. 看到 Harbor、固定服务器、`latest` 的脚本，默认先当历史/内部入口处理，不要直接用于客户安装或升级。
+4. 看到 Harbor、固定服务器、`latest` 的脚本，默认先当历史/内部入口处理，不要直接用于客户安装或升级。
+5. `generate-shared-test-env.ps1` 只给共享测试机或内部联调用，客户交付不要把它当安装器。
 
 ## 四、常见流程