ranshaodong/JuYou
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化

Browse Source
This commit is contained in:
Ran
2026-08-25 17:59:42 +08:00
commit 4b7380dd9b
408 changed files with 327400 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
文档/项目架构文档.md
+687
View File
@@ -0,0 +1,687 @@
# JuYouAI 项目架构文档
## 1. 架构概览
项目采用“双前端、单 Go 服务进程”的结构：
- `WEB`：面向普通用户的创作端。
- `ADMIN`：面向管理员的运营管理端。
- `API`：Go 后端，同时承载 HTTP API、静态文件托管、异步任务 Worker 和定时任务。
- PostgreSQL：保存用户、项目、任务、积分、渠道和媒体元数据，是业务状态的主要数据源。
- Redis：提供 Asynq 队列和运行时缓存，不作为业务任务最终状态的数据源。
- 腾讯云 COS：保存图片、音频、视频和任务结果等二进制对象。
- 第三方渠道：由 ADMIN 动态配置基础网址和 API Key，后端统一调用。
```mermaid
flowchart LR
User["用户浏览器"] --> Nginx["Nginx"]
AdminUser["管理员浏览器"] --> Nginx
Nginx -->|"/"| WebStatic["WEB 静态文件"]
Nginx -->|"/admin/"| AdminStatic["ADMIN 静态文件"]
Nginx -->|"/api/web/*"| API["Go API 进程"]
Nginx -->|"/api/admin/*"| API
API --> PostgreSQL["PostgreSQL"]
API --> Redis["Redis / Asynq"]
API --> COS["腾讯云 COS"]
API --> Channel["第三方渠道接口"]
Redis --> Worker["同一 Go 进程内的 Worker"]
Worker --> PostgreSQL
Worker --> COS
Worker --> Channel
Worker --> LocalMedia["FFmpeg / Python 语音识别"]
```
生产环境由一个名为 `juyou_ai` 的 systemd 服务启动 Go 二进制，进程内部并行运行 HTTP Server 和 Asynq Worker。
## 2. 根目录结构
```text
JuYouAI/
├─ WEB/ 用户端 Vue 应用
├─ ADMIN/ 管理端 Vue 应用
├─ API/ Go API、Worker、迁移和部署文件
├─ 文档/ 架构、部署和业务说明
├─ docker-compose.yml Windows 本地 PostgreSQL、Redis
├─ start_api.bat Windows 本地 API 启动脚本
└─ vite-port.ts 两个前端共用的开发端口选择逻辑
```
三个应用相互独立安装依赖，但前端构建结果会进入 API 目录：
```text
WEB build → API/static/web/
ADMIN build → API/static/admin/
Go build → API/bin/jcf-api
```
## 3. 技术栈
### 3.1 用户端和管理端
| 类别 | 技术 |
| ------ | -------------------------------------------------------- |
| 框架 | Vue 3 |
| 语言 | TypeScript |
| 构建 | Vite 5 |
| 路由 | Vue Router 4 |
| 状态 | Pinia |
| 请求 | Axios |
| 组件库 | Element Plus |
| 图标 | Element Plus Icons；WEB 通过 `src/icons.ts` 提供语义映射 |
| 图表 | ECharts，仅 WEB 使用 |
| 样式 | SCSS、统一变量文件和全局样式 |
### 3.2 后端
| 类别 | 技术 |
| ------------ | ------------------------------------------ |
| 语言 | Go 1.26 |
| HTTP 框架 | Gin |
| ORM | GORM |
| 数据库 | PostgreSQL 16 |
| 队列 | Asynq |
| 队列存储 | Redis 7 |
| 对象存储 | AWS SDK v2，通过 S3 协议访问腾讯云 COS |
| 身份认证 | JWT、随机 Refresh Token |
| 密码哈希 | Argon2id |
| 敏感配置加密 | AES-256-GCM |
| 本地媒体处理 | FFmpeg、FFprobe、Python |
## 4. 前端总体架构
`WEB` 和 `ADMIN` 都遵循相同的基础分层：
```text
main.ts
├─ 注册 Pinia
├─ 注册 Vue Router
├─ 注册 Element Plus 中文语言包
└─ 加载全局样式
views/ 路由级页面，负责编排业务页面
layouts/ 页面整体框架、侧栏和内容区
components/ 可复用展示和交互组件
composables/ 跨组件复用的组合式逻辑
features/ 按业务功能聚合的前端实现（按需使用）
api/ Axios 实例及业务接口封装
stores/ 登录态、提示消息和界面状态
utils/ 时间、下载、媒体、计费展示等纯工具
assets/ 图片、统一样式变量和全局样式
icons.ts WEB 语义图标到 Element Plus Icons 的统一映射
```
两个前端通过 Vite 动态导入路由页面，降低首次加载体积。API 请求均使用相对地址，开发环境由 Vite 代理，生产环境由 Nginx 代理，因此前端不保存后端服务器地址和第三方密钥。
### 4.1 样式组织
两个前端分别维护：
```text
src/assets/styles/variables.scss
src/assets/styles/main.scss
```
- `variables.scss` 定义颜色、边框、圆角、间距等统一语义变量。
- `main.scss` 放置全局重置、公共基础样式和组件库覆盖。
- 页面或组件自身样式放在对应 `.vue` 的 scoped style 或同名样式文件中。
- WEB 业务页面和组件的颜色均通过 `variables.scss` 中的语义令牌引用；ECharts 等 Canvas 场景先从 CSS 令牌读取实际色值。
- WEB 当前不使用渐变色，也不在业务组件中直接散落十六进制或 `rgb/rgba` 色值。
- 复杂组件按职责拆分样式。例如 `AssetPanel` 依次加载核心布局、媒体状态、预览覆盖和全局对话框主题文件。
- 响应式布局主要通过统一断点下的媒体查询实现。
## 5. WEB 用户端
### 5.1 入口和地址
| 项目 | 值 |
| --------- | ------------------------------------ |
| 入口 | `WEB/src/main.ts` |
| 路由 | `WEB/src/router/index.ts` |
| API 前缀 | `/api/web` |
| Vite base | `/` |
| 构建输出 | `API/static/web` |
| 开发端口 | 从 `127.0.0.1:5501` 开始选择可用端口 |
### 5.2 路由和业务页面
| 前端路由 | 页面 | 主要职责 |
| ------------------------------------------------- | --------------------------------- | -------------------------------- |
| `/login` | `LoginView.vue` | 用户登录 |
| `/drama-projects` | `RedrawProjectsView.vue` | 短剧创作项目列表 |
| `/drama-projects/:projectId` | `DramaProjectView.vue` | 短剧项目和剧集管理 |
| `/drama-projects/:projectId/episodes/:episodeId` | `DramaWorkbenchView.vue` | 短剧分镜工作台 |
| `/redraw-projects` | `RedrawProjectsView.vue` | 剧本反推项目列表 |
| `/redraw-projects/:projectId` | `RedrawProjectView.vue` | 反推项目详情 |
| `/redraw-projects/:projectId/episodes/:episodeId` | `RedrawWorkbenchView.vue` | 视频分析、字幕、反推与生成工作台 |
| `/script-analysis` | `ScriptAnalysisView.vue` | 剧本分析列表 |
| `/script-analysis/:scriptId` | `ScriptAnalysisWorkbenchView.vue` | 剧本分析处理页 |
| `/account` | `AccountView.vue` | 个人资料、积分和消费记录 |
`RedrawProjectsView.vue` 通过路由元信息区分短剧创作和剧本反推列表，复用同一套项目列表逻辑。
### 5.3 主要组件
`WEB/src/components/creative/` 是创作工作台的公共组件区，主要包含：
- 项目创建和编辑对话框；
- 素材面板、素材提示词编辑器；
- 模型和提示词配置对话框；
- 分镜时间线、任务状态和结果历史；
- 视频播放器、视频对比和加载状态；
- 剧本导入、剧本分析结果；
- 反推来源、文本、剧本和素材面板。
其中 `AssetPanel.vue` 的样式按职责拆分为：
```text
AssetPanel.core.scss 面板主体、资产卡片和编辑器基础布局
AssetPanel.media.css 资产操作、历史记录和分镜媒体状态
AssetPanel.preview.css 预览尺寸、缩放入口和播放器覆盖
AssetPanel.dialog.css 非 scoped 的预览对话框全局主题
```
这些文件保持固定加载顺序，同名选择器按该顺序形成稳定的覆盖关系。WEB 图标统一从 `@/icons` 语义映射或 `@element-plus/icons-vue` 引入，不再依赖 Lucide。
页面负责组合这些组件，公共请求和 URL 组装由 `WEB/src/api/creative.ts` 统一封装。
### 5.4 登录态和请求处理
用户端的认证数据保存在浏览器 `localStorage`：
```text
web_access_token
web_refresh_token
web_profile
```
请求流程：
1. Axios 请求拦截器读取 `web_access_token`，写入 `Authorization: Bearer ...`。
2. 后端返回 401 时，前端使用 Refresh Token 请求 `/api/web/auth/refresh`。
3. 同一时间只允许一个刷新请求，其余失败请求复用该 Promise。
4. 刷新成功后重放原请求。
5. 刷新失败后清理本地登录态并跳转登录页。
用户端还会在创建、分析、生成、取消任务后通知积分余额刷新；发现响应中仍有活动任务时会节流同步余额。
## 6. ADMIN 管理端
### 6.1 入口和地址
| 项目 | 值 |
| --------- | ------------------------------------ |
| 入口 | `ADMIN/src/main.ts` |
| 路由 | `ADMIN/src/router/index.ts` |
| API 前缀 | `/api/admin` |
| Vite base | `/admin/` |
| 构建输出 | `API/static/admin` |
| 开发端口 | 从 `127.0.0.1:5500` 开始选择可用端口 |
### 6.2 页面职责
| 前端路由 | 页面 | 主要职责 |
| ------------------- | --------------------- | ------------------------------------ |
| `/login` | `LoginView.vue` | 管理员登录 |
| `/redemption-codes` | `RedemptionsView.vue` | 兑换码批次和兑换码管理 |
| `/styles` | `StylesView.vue` | 项目风格管理和排序 |
| `/prompts` | `PromptsView.vue` | 系统提示词、历史版本和状态管理 |
| `/channels` | `ChannelsView.vue` | 第三方渠道网址、密钥、汇率和并发限制 |
| `/models` | `ModelsView.vue` | 渠道下的模型配置和价格管理 |
| `/users` | `UsersView.vue` | 用户创建、批量操作、状态和积分管理 |
| `/security` | `SecurityView.vue` | 管理员密码和安全操作 |
### 6.3 通用管理页面结构
- `AdminLayout.vue`：管理后台整体布局。
- `AdminMenu.vue`：后台导航菜单。
- `MasterDetailLayout.vue`：列表与详情编辑的公共布局。
- `PageHeader.vue`：统一页面标题区。
- `AdminNumberInput.vue`：统一数字输入行为。
- `ChannelFormFields.vue`：渠道连接、密钥、汇率和并发限制表单。
- `AppIcon.vue`：第三方图标库的统一封装。
渠道的完整 API Key 只在新增或主动更换时提交。查询渠道列表时，后端只返回掩码，不把完整密钥返回浏览器。
### 6.4 管理员认证和二次认证
管理端在 `localStorage` 保存：
```text
admin_access_token
admin_refresh_token
admin_profile
```
Access Token 过期后的刷新机制与 WEB 类似。创建兑换码批次等敏感操作还需要调用 `/api/admin/auth/reauth` 完成短时二次认证，随后通过 `X-Admin-Reauth-Token` 提交受保护请求。
## 7. 后端分层
后端入口是 `API/cmd/api/main.go`。启动时按依赖顺序完成配置加载、数据库连接、Redis 连接、安全组件、存储组件、Service、Handler、Worker 和 HTTP Server 组装。
```mermaid
flowchart TD
Route["Gin Route"] --> Middleware["认证、CORS、Trace ID、Recovery"]
Middleware --> Handler["handler：HTTP 参数和响应"]
Handler --> Module["modules：独立业务模块公开接口"]
Handler --> Service["service：共享业务规则和事务"]
Module --> Service
Module --> DB
Service --> Model["model：领域数据结构"]
Service --> DB["PostgreSQL / GORM"]
Service --> Queue["Asynq Client"]
Handler --> Storage["COS 文件流"]
Queue --> Worker["worker：后台任务"]
Worker --> DB
Worker --> Provider["provider：第三方渠道协议"]
Worker --> Storage
```
### 7.1 后端目录职责
| 目录 | 职责 |
| -------------------- | ------------------------------------------- |
| `cmd/api/` | 进程入口、依赖组装、启动和优雅关闭 |
| `internal/config/` | 读取并校验环境变量 |
| `internal/server/` | Gin、路由、中间件、静态站点托管 |
| `internal/handler/` | HTTP 参数解析、上传限制、状态码和响应 |
| `internal/modules/` | 按业务边界组织的独立模块及公开 Service 接口 |
| `internal/service/` | 业务规则、数据库事务、任务创建和资源删除 |
| `internal/model/` | GORM 模型和领域数据结构 |
| `internal/database/` | PostgreSQL 连接、空库基线和兼容初始化 |
| `internal/cache/` | Redis 普通客户端 |
| `internal/queue/` | Asynq 客户端、服务端和任务类型 |
| `internal/worker/` | 生成、媒体分析、短剧解析、剧本分析任务 |
| `internal/provider/` | 第三方渠道 HTTP 协议适配 |
| `internal/storage/` | COS 对象存储封装 |
| `internal/security/` | 密码哈希、JWT、Refresh Token、密钥加解密 |
| `internal/billing/` | 任务计费、积分预扣、结算和退款 |
| `internal/drama/` | 短剧文本内容处理 |
| `internal/media/` | 媒体命名等公共规则 |
| `internal/datetime/` | Asia/Shanghai 时间语义 |
| `workers/` | Python 本地语音识别脚本 |
| `migrations/` | 正式环境增量数据库迁移 |
| `static/` | WEB 和 ADMIN 构建产物 |
### 7.2 独立业务模块
后端包含两个独立业务模块目录，并在 `cmd/api/main.go` 完成依赖装配：
| 模块 | 目录 | 对外职责 |
| ---------- | -------------------------- | ---------------------------------------------------------------------- |
| 管理业务 | `internal/modules/admin/` | 模型列表与保存、文本模型计费校验、兑换码查询与批量生成、管理员操作审计 |
| 提示词业务 | `internal/modules/prompt/` | 系统提示词与版本历史、用户提示词查询和选择、自定义提示词增删改 |
调用关系如下：
```mermaid
flowchart LR
Main["cmd/api/main.go"] --> AdminModule["modules/admin.Service"]
Main --> PromptModule["modules/prompt.Service"]
AdminHandler["handler/AdminData"] --> AdminModule
AdminHandler --> PromptModule
CreativeHandler["handler/Creative"] --> PromptModule
AdminModule --> DB["GORM / PostgreSQL"]
PromptModule --> DB
```
模块通过构造函数接收数据库依赖，并使用明确的参数、返回值和错误类型对外提供能力。Handler 通过模块公开接口调用业务能力，模块测试位于各自目录的 `service_test.go`。
### 7.3 Handler、Service、Worker 边界
Handler 负责：
- 读取路径、Query、JSON 和 multipart 参数；
- 验证文件体积和基础输入格式；
- 从认证上下文取得用户或管理员；
- 调用 Service；
- 统一输出 HTTP 状态码、错误码和 Trace ID。
当前 `internal/handler/` 已不再通过 `h.service.DB`、`h.data.DB` 或同类入口直接执行 GORM 查询和事务。重绘、剧集和资产媒体上传所需的目标校验、记录写入、旧媒体缓存及记录清理由 `internal/service/creative_media.go` 统一提供。
Service 负责：
- 业务权限和资源归属判断；
- 项目、剧集、素材、分镜和任务规则；
- 数据库事务和行锁；
- 积分预扣、结算或退款；
- 创建持久任务并发送 Asynq 唤醒消息。
Worker 负责：
- 从 PostgreSQL 重新读取任务和配置快照；
- 调用第三方渠道；
- 轮询异步结果；
- 下载结果并写入 COS；
- 执行本地 FFmpeg、FFprobe 和 Python 处理；
- 持久化任务状态、输出和计费结果；
- 服务重启后恢复运行中的持久任务。
## 8. HTTP API 架构
### 8.1 API 分区
| 前缀 | 使用方 | 认证 |
| ------------------- | -------------------------------- | ------------------------------- |
| `/health` | 运维健康检查 | 无 |
| `/api/web/health` | WEB 健康检查 | 无 |
| `/api/web/auth/*` | 用户登录、刷新、退出 | 登录接口无 Access Token |
| `/api/web/*` | 用户账户和创作业务 | Web JWT |
| `/api/admin/health` | ADMIN 健康检查 | 无 |
| `/api/admin/auth/*` | 管理员登录、刷新、退出和二次认证 | 按接口区分 |
| `/api/admin/*` | 后台资源管理 | Admin JWT，敏感接口增加二次认证 |
### 8.2 通用中间件
Gin 全局中间件顺序包括：
1. Trace ID：复用请求的 `X-Request-ID`，没有时生成 UUID，并写回响应头。
2. 开发日志：仅 `DEBUG=true` 时启用 Gin Logger。
3. Recovery：捕获未处理 panic。
4. CORS：仅允许 `CORS_ORIGINS` 中明确配置的来源。
HTTP Server 主要超时：
| 配置 | 时间 |
| ------------------- | ------ |
| Read Header Timeout | 5 秒 |
| Read Timeout | 30 秒 |
| Write Timeout | 5 分钟 |
| Idle Timeout | 60 秒 |
| 优雅关闭等待 | 10 秒 |
长时间生成任务不会占用一个 HTTP 请求等待完成。HTTP 接口只创建任务，页面通过任务查询接口获取进度。
## 9. 身份认证和安全
### 9.1 用户和管理员隔离
用户和管理员使用不同的数据表、Token Claims、接口前缀和前端存储键：
| 类型 | 账号表 | Refresh Token 表 | Access Token 类型 |
| ------ | ------------- | ---------------------- | ----------------- |
| 用户 | `web_users` | `web_refresh_tokens` | `web_access` |
| 管理员 | `admin_users` | `admin_refresh_tokens` | `access` |
- 密码使用 Argon2id 哈希，不保存明文。
- Access Token 使用 JWT HS256 签名。
- Refresh Token 使用加密安全随机数生成，数据库只保存哈希。
- 管理员二次认证令牌有效期为 5 分钟。
- 渠道 API Key 使用 `CONFIG_ENCRYPTION_KEY` 进行 AES-256-GCM 加密。
### 9.2 请求追踪
前后端错误处理会携带或展示：
```text
错误码
错误描述
X-Request-ID / trace_id
```
运维使用请求追踪 ID 对照 API 日志定位请求。第三方响应体限制长度后进入错误信息，日志不记录认证请求头和密钥。
## 10. 异步任务架构
### 10.1 任务类型
Asynq 当前注册的任务包括：
| 队列任务 | 处理器 | 用途 |
| ----------------------- | ---------------------- | ---------------------------------- |
| `ai:dispatch-channel` | Generation Worker | 按渠道和用户并发限制选取待提交任务 |
| `ai:submit-task` | Generation Worker | 向第三方渠道提交生成任务 |
| `ai:poll-task` | Generation Worker | 轮询第三方异步任务 |
| `ai:download-task` | Generation Worker | 下载完成结果并写入 COS |
| `media:analyze-episode` | Media Worker | 视频探测、抽帧、语音识别和内容反推 |
| `drama:parse-episode` | Drama Parse Worker | 解析剧集文本并形成结构化内容 |
| `script:analyze` | Script Analysis Worker | 执行剧本分析任务 |
队列名称主要为 `ai`，Asynq Worker 并发数由 `AI_WORKER_CONCURRENCY` 控制。
### 10.2 生成任务状态流
```mermaid
stateDiagram-v2
[*] --> pending_submission
pending_submission --> submitting: 调度器取得渠道槽位
submitting --> submitted: 上游返回任务 ID
submitting --> result_ready: 上游直接返回结果 URL
submitting --> submit_unknown: 无法确认提交结果
submitted --> processing: 轮询仍在处理
processing --> result_ready: 上游完成
result_ready --> downloading
downloading --> succeeded: COS 持久化成功
pending_submission --> cancelled
submitted --> cancel_requested
processing --> cancel_requested
cancel_requested --> cancelled
submitting --> failed
submitted --> failed
processing --> failed
downloading --> failed
```
实际状态更新以 PostgreSQL `generation_tasks` 为准。Redis 中的 Asynq 任务只负责唤醒处理逻辑，Redis 队列长度不代表业务任务状态。
### 10.3 持久任务流程
1. WEB 发起分析或生成请求。
2. Service 在 PostgreSQL 事务中校验用户、项目、渠道、配置和积分。
3. 创建 `generation_tasks` 等持久任务记录，必要时预扣积分。
4. 向 Redis/Asynq 写入轻量任务 ID。
5. Worker 根据 ID 回查 PostgreSQL，完整业务快照保存在 PostgreSQL。
6. 调度器使用数据库锁和 `SKIP LOCKED` 控制多 Worker 竞争，并执行渠道总并发、单用户并发限制。
7. Worker 解密渠道密钥并提交第三方请求。
8. 异步上游由轮询任务持续更新状态；直接结果跳过轮询。
9. 完成后将结果下载到本地临时文件，再上传 COS。
10. 在数据库事务中创建 `generation_outputs`、更新分镜或素材的活动输出并结算积分。
11. 失败或取消时按业务规则退款、保留预扣或记录错误。
### 10.4 重启恢复
Go 进程启动时会执行恢复逻辑：
- 找出 `pending_submission` 任务，重新唤醒渠道调度；
- 找出 `submitted`、`processing` 和部分 `cancel_requested` 任务，恢复轮询；
- 找出 `result_ready`、`downloading` 任务，恢复结果下载；
- 把中断的剧本分析处理状态恢复到可重新消费状态；
- 恢复短剧解析任务。
因此 PostgreSQL 中的任务记录是恢复依据。Redis 清理或状态变化不改变 PostgreSQL 中持久化的业务任务状态。
## 11. 数据库架构
### 11.1 数据领域
| 领域 | 主要数据表 |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| 管理员安全 | `admin_users`、`admin_refresh_tokens`、`admin_audit_logs` |
| 用户账户 | `web_users`、`web_refresh_tokens` |
| 积分和兑换 | `point_ledger`、`point_grants`、`point_ledger_allocations`、`point_packages`、`redemption_batches`、`redemption_codes` |
| 渠道和模型 | `channels`、`channel_balance_snapshots`、`models`、`model_prices`、`user_model_configs`、`project_model_configs` |
| 提示词和风格 | `prompts`、`user_prompt_preferences`、`project_styles` |
| 创作项目 | `creative_projects`、`project_episodes`、`project_assets`、`episode_storyboards`、`episode_sources` |
| 短剧解析 | `drama_import_sessions`、`drama_parse_batches`、`drama_parse_tasks`、`episode_continuity_contexts` |
| 生成任务 | `generation_tasks`、`generation_outputs` |
| 剧本分析 | `script_analyses`、`script_analysis_characters` |
| 媒体 | `media_assets`、`channel_asset_cache` |
| 其他运营 | `announcements`、`payment_configs`、`recharge_orders`、`inspiration_gallery_items` 等 |
### 11.2 数据库初始化和迁移
数据库结构有三个相关机制：
1. 空库基线：`API/internal/database/schema.sql` 通过 `go:embed` 编译进二进制。数据库完全没有业务表时，API 启动会在事务中执行该基线。
2. 缺表补全：启动时只对不存在的 GORM 模型表执行 `AutoMigrate`，不会依赖 AutoMigrate 修改已有表的全部结构。
3. 增量迁移：生产部署脚本按文件名执行 `API/migrations/*.up.sql`，成功后记录在 `jcf_schema_migrations`。
`internal/database/postgres.go` 还包含旧安装兼容 DDL。数据库结构由 GORM Model、空库基线和增量迁移共同表达，部署脚本负责执行正式迁移。
### 11.3 数据库连接语义
- 时区固定为 `Asia/Shanghai`。
- GORM 最大连接数为 20，最大空闲连接数为 5。
- 单连接最长复用时间为 30 分钟。
- 启动时先 Ping PostgreSQL，连接失败则整个进程退出。
## 12. Redis 和队列
Redis 使用两个逻辑 DB：
| 配置 | 默认值 | 用途 |
| ---------------- | ------ | --------------------------- |
| `REDIS_DB` | `0` | 普通 Redis 客户端和健康检查 |
| `ASYNQ_REDIS_DB` | `1` | Asynq 队列 |
API 启动时会同时检查 PostgreSQL 和 Redis。任一基础依赖无法连接，服务不会继续启动。
Redis 数据用于队列和调度，PostgreSQL 保存任务真实状态、租约、上游任务 ID、错误和计费结果。
## 13. 媒体和对象存储
### 13.1 COS 存储职责
COS 保存：
- 用户头像和上传素材；
- 视频源文件、字幕、音频；
- 视频抽帧和缩略图；
- 本地识别结果；
- 第三方原始响应；
- 图片和视频生成结果。
PostgreSQL 的 `media_assets` 保存对象键、公开 URL、MIME、大小、SHA-256、显示名称和归属关系，不把大文件二进制放入数据库。
### 13.2 本地媒体处理
Media Worker 调用：
- FFprobe：读取时长、分辨率等媒体信息；
- FFmpeg：抽帧、提取音频和其他媒体转换；
- Python 脚本：执行本地语音识别；
- 第三方渠道：执行文本或视觉内容反推；
- COS：持久化中间产物和最终结果。
临时文件处理完成后清理，长期资源进入 COS，并在数据库保留元数据。
## 14. 第三方渠道适配
渠道基础网址和 API Key 由 ADMIN 保存到 `channels` 表，具体业务模型配置保存在 `models` 表。渠道密钥以 AES-256-GCM 密文保存，只有 Worker 调用时解密。
`internal/provider/apimart/` 负责统一的渠道 HTTP 协议：
- Bearer Token 认证；
- 文本请求；
- 图片任务提交；
- 视频任务提交；
- 异步任务查询；
- 渠道余额查询；
- 上游错误码、`Retry-After` 和响应体截断。
Service 和 Worker 通过 `internal/provider` 中的适配器访问第三方接口。
## 15. 计费和积分
计费逻辑集中在 `internal/billing/`，而不是由前端计算最终扣费：
- 前端只展示估算价格和积分余额；
- Service 创建任务时计算预估积分并按规则预扣；
- Worker 从第三方响应或任务结果取得实际用量；
- 任务完成时结算，多退少补按现有业务规则执行；
- 失败、取消和上游状态不确定分别使用不同处理规则；
- `point_ledger` 保存流水，`point_grants` 和分配表支持永久积分批次的顺序扣减及原批次退款；
扣款、退款、任务终态和输出激活操作在数据库事务中执行，结算以后端持久数据为依据。
## 16. 静态文件和部署架构
### 16.1 开发环境
```mermaid
flowchart LR
WebDev["WEB Vite"] -->|"/api 代理"| Go["Go API :8123"]
AdminDev["ADMIN Vite"] -->|"/api 代理"| Go
Go --> PG["Docker PostgreSQL :25432"]
Go --> Redis["Docker Redis :26379"]
```
- `docker-compose.yml` 只启动 PostgreSQL 和 Redis。
- Go API 直接在 Windows 运行。
- WEB 和 ADMIN 分别运行 Vite 开发服务器。
- 当前两个 Vite 配置都把 `/api` 代理到 `127.0.0.1:8123`。
### 16.2 生产环境
```mermaid
flowchart LR
Internet["公网请求"] --> Nginx["Nginx :80/:443"]
Nginx -->|"静态文件"| Static["/opt/juyou_ai/static"]
Nginx -->|"API / Health"| Service["juyou_ai :8123"]
Service --> PG["本机 PostgreSQL"]
Service --> Redis["本机 Redis"]
```
- API 只监听 `127.0.0.1:8123`，不直接暴露公网。
- Nginx 提供 WEB 根路径和 `/admin/` 静态站点。
- `/api/`、`/health` 等请求反向代理到 Go API。
- systemd 服务名为 `juyou_ai`。
- 环境文件位于 `/etc/juyou_ai/juyou_ai.env`。
- Go 自身也具备静态文件托管能力，适合本地或没有 Nginx 的场景；生产环境主要由 Nginx 直接提供静态文件。
## 17. 配置边界
后端配置统一来自 `API/.env` 或生产环境文件，主要分为：
| 配置组 | 内容 |
| ---------- | ------------------------------------------------ |
| 应用 | 运行环境、Debug、监听地址、静态目录 |
| PostgreSQL | 主机、端口、库名、用户、密码或完整 URL |
| Redis | 主机、端口、密码、普通 DB、Asynq DB |
| JWT | 签名密钥和 Token 有效期 |
| 管理员引导 | 首次管理员账号和密码 |
| 密码哈希 | Argon2 参数 |
| 敏感配置 | 渠道密钥加密主密钥和版本 |
| COS | Region、Endpoint、Bucket、SecretId、SecretKey、公开域名、体积限制 |
| Worker | 并发、轮询间隔、HTTP 连接池、本地工具路径 |
| CORS | 允许访问 API 的前端来源 |
前端运行时不保存 COS SecretKey、渠道 API Key、数据库密码或 JWT Secret。浏览器只接收 API 输出的非敏感展示数据。
## 18. 测试与验证
### 18.1 后端测试
后端测试文件与实现同目录，覆盖计费、数据库基线、文本解析、Provider、Service、业务模块、Storage 和 Worker。`internal/modules/admin` 与 `internal/modules/prompt` 均包含模块级测试。运行：
```bash
cd API
go test ./...
```
涉及真实数据库的基线测试通过专用环境变量启用，默认不会连接生产数据库。
### 18.2 前端验证
两个前端的构建命令都会先执行 TypeScript/Vue 类型检查：
```bash
npm --prefix WEB run build
npm --prefix ADMIN run build
```
格式检查：
```bash
npm --prefix WEB run format:check
npm --prefix ADMIN run format:check
```
### 18.3 健康检查
```text
GET /health
GET /api/web/health
GET /api/admin/health
```
健康检查会同时验证 PostgreSQL 和 Redis 连接。