# 运维手册

## 环境

- Windows 11、Linux 或 macOS
- Python 3.11+
- 可访问目标官方站点的网络
- Node 仅用于运行前端契约测试，不是生产运行依赖

## 日常命令

```powershell
# 更新并构建
.\.venv\Scripts\python.exe scripts\update_all.py

# 固定日期回归，不用于生产快照
.\.venv\Scripts\python.exe scripts\update_all.py --now 2026-08-12

# 仅重新构建
.\.venv\Scripts\python.exe scripts\build_site.py --site-url https://intel.example.com

# 本地访问
.\.venv\Scripts\python.exe scripts\serve.py --port 8765
```

## 部署

`dist/` 是完整静态目录，可交给 IIS、Nginx、对象存储或任何 CDN。运行服务器不需要 Python；Python 只在更新节点运行。IIS 必须将实际静态文件优先于 SPA fallback，否则 `/data/*.json` 会错误返回首页 HTML。

更新节点和 Web 节点分离时，将成功构建的 `dist/` 整目录同步到新版本目录，再通过目录链接或发布槽切换；不要边复制边对外提供半成品。

## 监控

至少监控：

- 进程退出码和最后成功时间。
- `source_target == source_success`。
- 核心栏目数量突降超过 30%。
- `textile-intelligence-source-status.json` 的失败源、HTTP 状态、证据词缺失和内容指纹变化。
- `dist/sitemap.xml`、`dist/llms.txt` 和两份公开 JSON 可访问且 Content-Type 正确。

## 故障处理

- 单个官方源失败：先核验 URL、重定向、证书和正文证据；不要直接删证据词或关闭 TLS 验证。
- 参考趋势源 403：允许跳过，不影响严格发布；长期失效再从趋势配置删除。
- 翻译代理不可用：保留本站中文摘要和官方原文，不阻断发布。
- 构建失败：正式 `data/` 与 `dist/` 保持上一版；修复后重跑。
- 数据误判：先修共享规范化或分类函数并加最小回归测试，再重新生成，避免只在前端隐藏。

## 备份和清理

`runtime/snapshots/` 自动保存旧 JSON 的 gzip 快照，限制为 14 份和 120 MiB。源码库不提交 `dist/`、`.venv/`、临时更新目录和快照。若迁移到数据库，备份策略由数据库负责，仍应保留每日成功 JSON 作为可重放交换快照。

## 发布清单

1. Python 与 Node 测试全绿。
2. 严格源全部通过，活动源全部通过。
3. `SANSHENG_SITE_URL` 是正式唯一域名。
4. 桌面、390px 与 375px 检查七入口、日历、展会、平台、活动和趋势图库。
5. 抽查外文、简中、`.cn`、繁中页面的翻译按钮门控。
6. 抽查 10 条详情页的 canonical、JSON-LD、官方链接和日期。
7. 发布后请求 `/data/textile-intelligence.json`，确认不是 SPA HTML。