docs: 更新 main 私有化部署指南

README.md

@@ -1,6 +1,6 @@
 # KOC LOOP
 
-KOC 内容分发与数据回收闭环。当前私有化分支运行于标准 Next.js Node.js、MySQL 8、Nginx 和本地持久化文件存储。
+KOC 内容分发与数据回收闭环。`main` 分支运行于标准 Next.js Node.js、MySQL 8、Nginx 和本地持久化文件存储。
 
 ## Prerequisites
 
@@ -45,13 +45,21 @@ npm run build
 
 ## KOC 资源导入
 
-超级管理员和管理员可在“KOC资源”页面下载标准 Excel 模板，批量导入已有资源。模板只需填写小红书账号主页，合作来源可选填；上传后系统自动解析账号名称、小红书号、IP属地和粉丝数。
+超级管理员和管理员可在“KOC资源”页面下载标准 Excel 模板，批量导入已有资源。模板只需填写账号主页；账号名称、账号 ID、IP 属地、粉丝数、性别、简介、标签和合作来源均可选填。多个标签使用逗号分隔，每个账号最多 5 个标签。
 
-- 单次最多导入 100 个账号，支持 `.xlsx` 和 `.csv`，文件不超过 5MB。
+- 单次最多导入 10,000 个账号，支持 `.xlsx` 和 `.csv`，文件不超过 20MB。
-- 当前自动解析支持小红书账号主页；上传后先展示新增、更新和异常数据，存在异常时不会写入数据库。
+- 当前自动解析支持小红书账号主页；上传后先展示新增、更新和异常数据。异常行会跳过，其余有效账号可以正常导入。
 - 按“平台 + 账号主页”去重；解析出相同小红书号时也会更新已有账号。
 - 重复账号更新公开资料和合作来源，不产生两份资源。
-- 导入的合作来源会进入现有资源搜索、筛选和导出结果。
+- 大批量导入会先写入资源库，再在后台逐步补全缺失的公开资料。
+- KOC 使用手机号或微信号领取任务后，系统会把该值写入“当前联系人”；原“合作来源”继续保留渠道信息。
+- 导入的标签、当前联系人和合作来源会进入资源搜索或导出结果。
+
+## KOC 批量回填 Excel
+
+KOC 领取端支持导出和上传批量回填表。视频任务只生成“序号、标题、笔记内容、视频、发布链接、笔记截图、数据分析截图”列，不生成“图片”列。视频链接通过当前公网域名生成，下载接口返回可播放的 `.mp4` 附件。
+
+反向代理部署必须正确传递 `Host`、`X-Forwarded-Host` 和 `X-Forwarded-Proto`，并把 `APP_ORIGIN` 配置为实际公网地址；不要填写 `localhost` 或容器内部地址。
 
 ## Agent MCP
 

docs/KOC LOOP 私有化部署指南.md

@@ -1,6 +1,6 @@
 # KOC LOOP 私有化部署指南
 
-本文适用于 `codex/self-hosted-mysql` 分支。目标架构是运维提出的：Nginx 代理 + KOC 服务 + MySQL 数据库，并让后台、外部 KOC 领取页和 Agent MCP 都能通过一个公网域名访问。
+本文适用于 `main` 分支。目标架构是运维提出的：Nginx 代理 + KOC 服务 + MySQL 数据库，并让后台、外部 KOC 领取页和 Agent MCP 都能通过一个公网域名访问。
 
 ## 1. 部署形态
 
@@ -35,7 +35,7 @@
 ```bash
 git clone ssh://git@gta.gbotai.cn:42001/wufengping/koc-loop.git
 cd koc-loop
-git checkout codex/self-hosted-mysql
+git checkout main
 cp .env.self-hosted.example .env.self-hosted
 ```
 
@@ -57,6 +57,8 @@ cp .env.self-hosted.example .env.self-hosted
 
 密钥必须由密码管理器生成，禁止提交到 Git、聊天、部署日志或 URL。三个业务密钥 `ADMIN_INTERNAL_TOKEN`、`KOC_MCP_API_KEY`、`AI_TOOL_CENTER_MCP_KEY` 不得复用。
 
+`APP_ORIGIN` 必须填写用户实际访问的 HTTPS 公网地址，不能填写 `localhost`、`app:3000` 或其他容器内部地址。Excel 中的视频下载链接会优先使用这个地址；前置网关还必须把原始 `Host`、`X-Forwarded-Host` 和 `X-Forwarded-Proto` 传给仓库内的 Nginx。
+
 ## 4. 首次启动
 
 ```bash
@@ -88,7 +90,9 @@ curl -fsS http://127.0.0.1:${HTTP_PORT:-80}/api/health
 3. 80 端口只做 301 跳转；
 4. 保留 `/koc/` 静态规则、`/api/mcp` 长连接规则和 `/` 反向代理规则。
 
-MCP 路由已经关闭代理缓冲并将超时时间延长到 1 小时，避免 Agent 的长调用被 Nginx 提前截断。
+MCP 路由已经关闭代理缓冲并将超时时间延长到 1 小时，避免 Agent 的长调用被 Nginx 提前截断。仓库内 Nginx 同时将上传限制设为 85 MB，用于接收最多 80 MB 的批量回填 Excel；公司网关或负载均衡的请求体限制也必须不低于 85 MB。
+
+视频下载接口必须经过 `/api/partner-image` 反向代理，正常响应应包含 `Content-Type: video/mp4` 和带 `.mp4` 文件名的 `Content-Disposition: attachment`。不要在网关层改写该响应类型或移除附件响应头。
 
 ## 6. 迁移原 Sites 数据
 
@@ -124,12 +128,13 @@ npm run db:import-json -- /backup/koc-d1-export.json
 
 导入脚本按业务依赖顺序写入，并使用主键/唯一键安全更新已有记录。正式迁移前先在测试库演练并核对任务数、笔记数、领取数、发布数和账号数。
 
-### 6.2 R2 图片导入
+### 6.2 R2 媒体文件导入
 
 把 R2 按原对象 key 导出到一个目录，目录层级必须保留，例如：
 
 ```text
 content-assets/...
+content-videos/...
 publish-evidence/...
 creator-center/...
 ```
@@ -141,7 +146,7 @@ UPLOAD_DIR=/data/koc/uploads \
   npm run storage:import -- /backup/koc-r2-export
 ```
 
-脚本会复制文件，并为缺少元数据的图片生成 Content-Type 元数据。容器部署时也可以在宿主机临时挂载 `upload_data` 卷后执行。
+脚本会复制文件，并为缺少元数据的媒体文件生成 Content-Type 元数据。容器部署时也可以在宿主机临时挂载 `upload_data` 卷后执行。
 
 ## 7. 上线验收
 
@@ -155,9 +160,11 @@ UPLOAD_DIR=/data/koc/uploads \
 6. 上传创作者截图并填写曝光量、阅读量；
 7. 后台立即采集一篇笔记成功；
 8. 保存次日采集计划，确认数据库产生 `collection_runs`；
-9. 导出的 Excel 内能直接看到原图和截图；
+9. 图文任务导出的 Excel 内能直接看到原图和截图；
-10. Agent 用 `KOC_MCP_API_KEY` 调用 `/api/mcp` 能发现全部工具；
+10. 视频任务导出的 Excel 不含“图片”列，包含“视频”列，点击链接能下载扩展名为 `.mp4` 且可正常播放的文件；
-11. 重启全部容器后数据与图片不丢失。
+11. 批量回填 Excel 可以上传，发布链接、笔记截图和单篇笔记数据分析截图均能正确回写；
+12. Agent 用 `KOC_MCP_API_KEY` 调用 `/api/mcp` 能发现全部工具；
+13. 重启全部容器后数据、图片和视频不丢失。
 
 ## 8. 备份与恢复
 
@@ -180,6 +187,8 @@ docker compose --env-file .env.self-hosted \
   -f docker-compose.self-hosted.yml up -d --build
 ```
 
+应用容器每次启动都会按文件名顺序执行尚未应用的 `mysql/*.sql`。本次版本包含平台/视频字段、账号性别/简介/标签以及“当前联系人”字段的增量迁移；升级后应检查容器日志确认 `0005`、`0006`、`0007` 已执行或已被识别为历史迁移。
+
 数据库迁移只允许向前追加新的 `mysql/*.sql` 文件，禁止修改已经在生产执行过的迁移。应用回滚到旧镜像前，要确认旧代码兼容当前数据库结构；涉及不可逆结构变化时，必须同时准备数据库恢复方案。
 
 ## 10. 运维排查
@@ -189,6 +198,9 @@ docker compose --env-file .env.self-hosted \
 | `/api/health` 返回 503 | 查看 MySQL 容器健康状态与应用数据库变量 |
 | 登录页可开但登录失败 | 确认迁移完成、超级管理员变量仅用于初始化 |
 | 配图或截图 404 | 检查 `upload_data` 卷和 `UPLOAD_DIR=/data/koc/uploads` |
+| Excel 视频链接出现 localhost 或无法访问 | 检查 `APP_ORIGIN`、公网域名和网关转发的 Host/Proto 请求头 |
+| 视频下载后不是 MP4 或无法播放 | 检查 `/api/partner-image` 是否经过应用代理、文件是否完整，以及网关是否保留 Content-Type/Content-Disposition |
+| 批量回填表上传返回 413 | 将公司网关、负载均衡和 Nginx 的请求体限制统一提高到至少 85 MB |
 | 09:00 未自动采集 | 检查 `ENABLE_SCHEDULER=true`、服务器日志和采集 MCP 网络 |
 | MCP 401 | 检查请求头是否为 `Authorization: Bearer <KOC_MCP_API_KEY>` |
 | 飞书读取失败 | 检查应用权限、文档授权和服务器到飞书 OpenAPI 的网络 |

docs/KOC LOOP 部署指南.md

@@ -1,4 +1,6 @@
-# KOC LOOP 部署指南
+# KOC LOOP Sites 旧版部署指南
+
+> 此文档仅适用于历史 `codex/sites-release-controls` 分支。`main` 已切换为 Next.js + MySQL + Nginx 私有化部署，正式部署请使用 [KOC LOOP 私有化部署指南](KOC%20LOOP%20私有化部署指南.md)，不要按本文把 `main` 发布到 Sites。
 
 KOC LOOP 由两个独立站点组成：