104 lines
7.8 KiB
Markdown
104 lines
7.8 KiB
Markdown
# Phase 0 技术决策
|
||
|
||
日期：2026-09-08
|
||
范围：P0-05；以下决策用于进入 Phase 1 的实施边界。未有实测依据的版本、容量和产品值明确标为待确认。
|
||
|
||
## 1. 已固定决策
|
||
|
||
### D-01 项目根目录和迁移边界
|
||
|
||
- 唯一实施根目录为 `E:\RD\Kaotings\www_site`。
|
||
- 不从 `kts_site` 或任何外部旧工程复制页面、代码、TTS 服务或配置。
|
||
- Phase 0 不移动、删除或重排现有文档和素材；业务目录在实际需要的阶段新增。
|
||
|
||
依据：V1.1 第 1.1、13.1、16 章及当前 Git 审计。
|
||
|
||
### D-02 代码组织
|
||
|
||
- Phase 1 Web 暂使用仓库根目录 App Router，承载官网、TTS 工作台、账户和业务管理页面；在 API/CMS/Worker 进入同仓库前不为单一 Web 应用增加额外 monorepo 层。后续若引入多应用，再迁入 `apps/web`，保持页面和组件边界不变。
|
||
- 业务 API 使用 `services/api`，统一负责身份、权限、权益、额度、任务和上游代理。
|
||
- Worker 使用 `services/worker`，以持久化任务表为恢复依据。
|
||
- CMS 采用同仓库独立落点 `apps/cms`，内容授权和 schema 与业务身份隔离。
|
||
- `packages` 仅在出现实际跨应用共享时创建，不为未来功能预建空壳。
|
||
- `infra` 保存部署、反向代理和无秘密示例配置。
|
||
|
||
这是一项新增落点决策，不代表目录已经存在。CMS 是否同机部署由测试机运行时和资源验证决定，但权限边界不改变。
|
||
|
||
### D-03 数据归属和持久化
|
||
|
||
- 业务数据库由 API 负责：用户、Session、Role/Plan、会员授权、额度账户/流水、TTS 任务、审计和任务关联音频元数据。
|
||
- CMS 数据由 Payload 负责，使用独立 schema 或数据库账号；CMS 迁移不得覆盖业务迁移。
|
||
- PostgreSQL 可以共用同一实例，但不共用迁移职责或数据库账号。当前测试机尚未安装或提供 PostgreSQL。
|
||
- 音频使用私有 S3 兼容对象存储（优先评估 MinIO 或已有兼容服务）；浏览器不得直接获得永久公开 URL。
|
||
- 原始文本和音频是用户私有数据；默认日志只保留任务 ID、长度、状态和耗时等脱敏信息。
|
||
|
||
### D-04 认证与授权
|
||
|
||
- API 是唯一业务身份权威；Next.js 不复制认证、额度或权限决策。
|
||
- 使用服务端可撤销的不透明会话，浏览器持有 `Secure`、`HttpOnly`、`SameSite` Cookie。
|
||
- Role 固定为 `user/admin`，Plan 固定为 `free/vip`，两者不合并。
|
||
- CSRF 和 Origin 校验由 API 对 Cookie 写操作实施；服务端逐接口检查账号状态、权限和资源归属。
|
||
- CMS 使用独立管理会话/授权；普通业务注册不能自动得到 CMS 权限。
|
||
- 初始管理员通过受控初始化建立，注册接口不能接受角色、套餐、状态或验证字段。
|
||
|
||
### D-05 任务和额度
|
||
|
||
- 任务采用数据库持久化状态 `queued -> running -> succeeded/failed`，Worker 使用租约和可恢复扫描。
|
||
- Redis 只用于限流、轻量协调或通知，不作为任务唯一事实来源。
|
||
- 接收任务时事务化冻结额度；音频持久化成功后转消费；失败释放；重播/下载不扣生成额度。
|
||
- 同一用户幂等键与请求绑定；同键不同请求返回冲突。上游不支持幂等时，不对结果不明的请求盲目自动重试。
|
||
- TTS 上游只能通过固定配置的适配器访问，用户输入不得控制请求 URL。
|
||
|
||
### D-06 代理和网络边界
|
||
|
||
- 浏览器只访问同源 HTTPS 业务入口；不直接访问 TTS、数据库、Redis 或对象存储管理端。
|
||
- TTS 上游保持内部服务边界；现有上游不重写，业务层做适配和安全代理。
|
||
- 外部入口目标为 80/443，80 跳转 HTTPS；实际反向代理产品尚未安装，Nginx/Caddy 在 Phase 1 选定。
|
||
- 测试机目前仅开放/监听 SSH，不能称为已部署环境。
|
||
|
||
### D-07 统一打包部署和版本核对
|
||
|
||
- 后续部署禁止依赖逐个文件的 `pscp`/手工覆盖；必须使用保留目录结构的统一归档包或等效同步方案，至少完整包含 `app/`、`components/`、`lib/`、`public/` 和运行配置。
|
||
- 部署包必须携带构建提交号和文件清单；解包后先核对目录、关键源码哈希和提交号，再执行安装与构建。
|
||
- 构建时注入 `NEXT_PUBLIC_BUILD_COMMIT` 或等效版本变量，启动后通过页面版本标识、构建产物和 CSS 资源核对实际提供版本。
|
||
- 重启前后必须确认监听进程的 PID、工作目录、启动命令和 `.next` 构建时间，避免旧进程继续提供旧构建。
|
||
- 部署失败或版本核对不一致时停止切换，不以 HTTP `200` 作为版本生效的唯一证据。
|
||
- 当前 Phase 1 已用版本标识临时验证；统一归档部署脚本、原子切换和自动核对列为后续部署基础设施任务。
|
||
|
||
### D-08 旧 Web、推理服务和 Phase 3 存储边界
|
||
|
||
- `KT26-0903_Big-TTS` 是旧 Web 应用，不作为新站运行时依赖；当前测试服务器未发现其 SQLite、进程、容器或监听端口。
|
||
- 新网站是用户、权限、额度、历史和 TTS 操作的唯一入口。旧工程不迁移用户、历史、音频或配置；当前测试环境未发现可迁移的旧运行数据。正式退役前仍需由旧系统负责人完成源端备份和替代验证确认。
|
||
- 底层推理服务保持独立，由 `services/api` 通过服务端环境配置调用；旧 Web 退役不等于停止推理服务。
|
||
- Phase 3 V1 最小契约固定为代码已验证的 `default` 音色、同步生成、WAV、服务端 Unicode 码点计量和 `speed=1`。旧客户端声明的 MP3、可变语速、其他音色不视为已验证能力。
|
||
- 测试阶段音频使用 `/home/flym/kaotings-audio` 私有本地目录，不把它写成已部署对象存储；持久卷、容量、保留期、清理和备份恢复仍是上线阻断项。
|
||
- 当前上游为公网 HTTP 地址，正式上线前必须改为 HTTPS 或受控加密通道，并限制来源；不修改只读授权的旧工程或上游服务器。
|
||
|
||
## 2. 尚未固定且不能虚构的事项
|
||
|
||
| 事项 | 当前处理 | 固定条件 |
|
||
| --- | --- | --- |
|
||
| Next.js/TypeScript/Tailwind 版本 | 待定 | Phase 1 选定版本并完成本地构建 |
|
||
| FastAPI/Python 依赖版本 | 待定 | Phase 2 建模前完成兼容性验证 |
|
||
| Payload 版本和 CMS 集成方式 | 待定 | 确认 Node 运行时和独立内容库方案 |
|
||
| PostgreSQL/Redis/对象存储版本 | 待定 | 测试机服务方案和持久卷确定后固定 |
|
||
| Nginx 或 Caddy | 待定 | 以 HTTPS、同源代理和运维能力验证为准 |
|
||
| TTS 协议、音色、参数和超时 | 待定 | 授权上游联调后写入契约 |
|
||
| 免费/VIP 额度和并发 | 待定 | 产品负责人提供值，配置版本化 |
|
||
| 音频/文本/日志/备份保留期 | 待定 | 产品和隐私要求确认后固定 |
|
||
| 域名、证书、备份位置 | 待定 | 环境负责人提供并验证 |
|
||
|
||
## 3. 模块责任边界
|
||
|
||
| 模块 | 责任 | 不负责 |
|
||
| --- | --- | --- |
|
||
| `apps/web` | 页面、表单、状态展示、同源 API 调用、可访问性 | 认证权威、额度扣减、上游密钥 |
|
||
| `services/api` | 认证、授权、权益、额度、任务 API、TTS 代理、资源归属 | 页面渲染、直接执行不可恢复长任务 |
|
||
| `services/worker` | 领取任务、调用适配器、音频校验/存储、结算/释放、恢复 | 浏览器会话和 CMS 权限 |
|
||
| `apps/cms` | 产品、媒体、首页内容、SEO 草稿/发布 | 业务用户密码、TTS 权益和额度 |
|
||
| `infra` | 运行配置、代理、迁移/备份/回滚说明 | 业务规则和秘密提交 |
|
||
|
||
## 4. 变更规则
|
||
|
||
如果真实 TTS 接口、服务器权限或版本兼容性与本文冲突，先新增差异记录并更新本文件，不以临时绕过方式破坏身份隔离、额度一致性或私网边界。任何服务器安装、扩容、开放端口和 HTTPS 切换都必须作为明确授权的运维动作单独执行。
|