# 宇之然内容创作平台 - 系统架构与部署指南 ## 系统组成 整个项目由两个核心部分组成： | 组件 | 位置 | 职责 | 状态 | |------|------|------|------| | **内容流水线** | `automation/scripts/` | 选-写-优-发 全自动化脚本 | 已实现 | | **管理平台** | `platform/` | Web管理界面 + API + 数据同步 | 新开发 | | **数据存储** | `automation/data/` | JSON 选题库 + 发布包 | 共享 | ### 1. 内容流水线（模块化） ``` collector.py → 收集热点 → automation/data/sustainability_topics.json creator.py → 创作内容 → automation/data/drafts/YYYY-MM-DD/ optimizer.py → 合规优化 → 生成 optimization_report.json publisher.py → 发布包生成 → automation/data/releases/ + content/published/ ``` **特点**： - 独立可运行，每个脚本都有 CLI 参数 - 数据文件基于日期组织 - 日志写入 `automation/logs/` ### 2. 管理平台（Web UI） ``` backend/ ├── app/ │ ├── main.py # FastAPI 入口 │ ├── database.py # SQLite 连接 │ ├── models.py # Topic, Article 模型 │ ├── schemas.py # Pydantic 验证 │ ├── api/ │ │ ├── system.py # 系统状态、流水线触发、日志查看 │ │ ├── topics.py # 选题 CRUD + 发布标记 │ │ ├── articles.py # 文章管理 │ │ └── publisher.py # 发布包生成与查看 │ └── core/ │ ├── generator.py # 调用 creator.py │ ├── optimizer.py # 调用 compliance_optimizer.py │ └── sync.py # JSON↔DB 同步 frontend/ └── index.html # Vue 3 + Element Plus SPA ``` **特点**： - 前端无构建，CDN依赖（Tailwind + Vue + Element Plus） - 数据通过 REST API 与后端交互 - 实时显示流水线状态 ## 部署方式：直接目录运行（不用 Docker） ### 前置条件 - Python 3.10+ - `pip install -r platform/backend/requirements.txt` - 确保自动化脚本可运行（`scripts/` 及其依赖已就绪） ### 启动步骤 ```bash # 1. 进入 platform 目录 cd /root/.openclaw/workspaces/yzr-yxl/projects/yu-zhi-ran/platform # 2. （首次）创建数据目录 mkdir -p data logs # 3. 启动服务器 ./run.sh 8001 # 或手动： cd backend python -m uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload ``` ### 访问 - 前端界面：http://localhost:8000/ - API 文档： http://localhost:8000/docs - 健康检查： http://localhost:8000/api/system/status ## 系统架构与数据流 ``` ┌─────────────────────────────────────┐ │ Frontend (Vue 3) │ │ 仪表盘 | 选题列表 | 预览 | 发布 │ └─────────────────┬───────────────────┘ │ HTTP API (JSON) ┌─────────────────▼───────────────────┐ │ FastAPI (backend/app) │ │ system | topics | publisher | api │ └─────────────────┬───────────────────┘ │ ┌─────────────────────┼─────────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ core/ │ │ core/ │ │ core/ │ │ generator │ │ optimizer │ │ sync │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └─────────────────────┼─────────────────────┘ │ subprocess (CLI) ┌─────────────────▼───────────────────┐ │ automation/scripts/*.py │ │ collector creator optimizer │ │ publisher (生成发布包) │ └─────────────────┬───────────────────┘ │ 读写 ┌─────────────────▼───────────────────┐ │ automation/data/ │ │ sustainability_topics.json │ │ drafts/ releases/ │ └─────────────────────────────────────┘ ``` ### 关键集成点 1. **触发创作** → `POST /api/system/generate/run` - FastAPI 调用 `generator.py → subprocess creator.py` - 成功后调用 `sync_all_topics()` 同步选题状态到数据库 2. **触发优化** → `POST /api/system/optimize/run` - `optimizer.py → subprocess compliance_optimizer.py` - 读取报告并更新数据库 3. **生成发布包** → `POST /api/publisher/generate/{topic_id}` - `publisher.py → subprocess publisher.py --topic-id {id}` - 发布包存到 `content/published/` 和 `automation/data/releases/` 4. **查看发布包** → `GET /api/publisher/package/{topic_id}/{platform}` - 返回 HTML 内容供前端 iframe 预览或复制 5. **流水线状态** → `GET /api/system/pipeline/status` - 检查日志文件最后修改时间和错误关键词 - 返回各模块健康状态 ## 目录结构对比：原 vs 新 ### 原（纯脚本） ``` yu-zhi-ran/ ├── automation/ # 流水线 ├── scripts/ # 同 automation/scripts（软链？） ├── content/ # 已发布内容 └── 手动操作（打开终端运行脚本） ``` ### 新（管理平台 + 流水线） ``` yu-zhi-ran/ ├── platform/ # 新增：Web管理平台 │ ├── backend/ │ │ ├── app/ │ │ │ ├── main.py │ │ │ ├── api/ │ │ │ └── core/ │ │ └── requirements.txt │ ├── frontend/ │ │ └── index.html │ └── run.sh # 启动脚本 ├── automation/ # 流水线（不变） ├── scripts/ # 流水线脚本（不变） └── (其他目录 unchanged) ``` **关系**：platform 读取 automation/data/ 的数据并调用 scripts/ 执行，不修改原有脚本。 ## 功能清单 | 功能 | 实现状态 | API端点 | 前端位置 | |------|---------|---------|---------| | 系统概览 | ✅ | `GET /api/system/status` | 仪表盘统计卡片 | | 选题列表 | ✅ | `GET /api/topics?status=` | 选题管理表格 | | 选题详情 | ✅ | `GET /api/topics/{id}` | 预览对话框 | | 触发创作 | ✅ | `POST /api/system/generate/run` | "运行创作任务"按钮 | | 触发优化 | ✅ | `POST /api/system/optimize/run` | "运行合规优化"按钮 | | 生成发布包 | ✅ | `POST /api/publisher/generate/{id}` | 发布Tab → "重新生成" | | 发布包预览 | ✅ | `GET /api/publisher/package/{id}/{platform}` | 发布Tab → "查看" | | 发布包复制 | ✅ | (同上) | 发布Tab → "复制HTML" | | 标记已发布 | ✅ | `POST /api/topics/{id}/publish` | 发布Tab → "确认发布" | | 流水线状态 | ✅ | `GET /api/system/pipeline/status` | 流水线状态面板 | | 同步数据 | ✅ | `POST /api/sync/run` | 全量刷新按钮 | | 日志查看 | ✅ | `GET /api/system/logs/{date}?log_type=` | 日志对话框 | ## 数据同步说明 **源**：`automation/data/sustainability_topics.json`（自动化脚本写入） **目标**：`platform/backend/data/yzr.db` (SQLite) **同步策略**： - **实时同步**：每次创作/优化任务完成后自动调用 `sync_all_topics()` - **手动同步**：前端 "全量刷新" 按钮 → `POST /api/system/refresh` - **定时同步**：可在 platform 启动时预先执行一次 **字段映射**： | JSON 字段 | Topic 模型字段 | |-----------|----------------| | `id` | `id` | | `title` | `title` | | `field` | `field` | | `status` | `status` | | `priority_score` | `priority_score` | | `compliance_score` | `compliance_score` | | `ready_at` | `ready_at` (date) | | `published_at` | `published_at` (date) | | `platform_urls` | `platform_urls` (JSON) | **状态对应**： - 自动化脚本使用中文状态：`"待处理"`, `"待发布"`, `"已发布"` 等 - 平台数据库保持中文状态（前端也显示中文） ## 扩展性 ### 添加新平台 1. 在 `automation/scripts/publisher.py` 的 `PLATFORMS` 添加配置 2. 在 `platform/backend/app/api/publisher.py` 的 `list_platform_packages()` 添加平台路径 3. 在前端 "发布管理" 对话框添加新平台的输入框 ### 定时任务 使用 crontab 定时运行自动化脚本： ```bash # 每天 5:00 收集选题 0 5 * * * cd /path/to/yu-zhi-ran && python automation/scripts/collector.py # 每天 9:00 生成内容（如果待处理选题充足） 0 9 * * * cd /path/to/yu-zhi-ran && python automation/scripts/creator.py # 每天 14:00 合规优化（可选） 0 14 * * * cd /path/to/yu-zhi-ran && python automation/scripts/optimizer.py # 每周一 10:00 发布（手动发布包生成） 0 10 * * 1 cd /path/to/yu-zhi-ran && python automation/scripts/publisher.py ``` ## 开发调试 ### 日志查看 ```bash # 实时 tail 日志 tail -f automation/logs/creator_$(date +%Y-%m-%d).log tail -f automation/logs/optimizer_$(date +%Y-%m-%d).log tail -f automation/logs/publisher_$(date +%Y-%m-%d).log ``` ### API 调试 访问 http://localhost:8000/docs 使用 Swagger UI 测试所有端点。 ### 前端调试 浏览器 DevTools → Network 查看 API 请求。 ## 故障排查 | 问题 | 可能原因 | 解决方案 | |------|---------|----------| | 前端显示无数据 | 数据库未同步 | 点击"全量刷新"或访问 `/api/system/sync/run` | | 创作按钮灰色 | 无可用选题 | 检查 `automation/data/sustainability_topics.json` 是否有 `status: "待处理"` | | 生成发布包失败 | HTML不存在 | 检查 `automation/data/releases/YYYY-MM-DD/` 是否存在对应HTML | | 端口占用 | 已有服务运行 | 停止旧的 uvicorn 进程或改端口 | | 依赖缺失 | pip install 未完成 | 运行 `pip install -r platform/backend/requirements.txt` | ## 后续优化建议 1. **数据库初始化**: 添加自动创建表 + 初始数据脚本 2. **权限控制**: 添加简单登录（当前无认证，仅本地访问） 3. **任务队列**: 耗时的流水线步骤改为异步（BackgroundTasks + 状态轮询） 4. **配置管理**: 将平台配置（PLATFORMS 的 enabled 状态）移到数据库 5. **备份策略**: 定期备份 `automation/data/` 和 `platform/data/` 6. **Docker 重构** (可选): 如需容器化，可分别构建 backend 和 nginx 镜像 ## 总结 - ✅ **无 Docker**：直接 `./run.sh` 启动，依赖 `requirements.txt` - ✅ **双系统集成**：管理平台（Web UI）调用自动化流水线（CLI脚本） - ✅ **数据同步**：JSON ↔ SQLite 自动/手动同步 - ✅ **状态监控**：流水线各模块健康状态面板 - ✅ **一键操作**：创作、优化、生成发布包全部通过 Web 界面触发 系统已准备好用于日常内容生产管理。 --- **维护者**: AI 助手小然 **最后更新**: 2026-04-19