Table of Contents

项目档案

文档状态
基本信息
DevHarness 来源与基线
子项目与交付单元
技术栈与运行环境

固定来源基线
运行栈
已验证的 MVP-0 本机基线（2026-08-20）
AutoMigrate 与代码生成结论

阅读入口
常用命令
目录边界
环境、配置与凭据
项目专用验收要求
MVP-0 完成状态（2026-08-21）
Provider 凭据风险决策与 #24 已交付实现（2026-08-22）
#38 统一本地服务启动入口（2026-08-24，验收通过）
#39 本机 Supervisor 三实例（2026-08-24，验收通过）

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

项目档案

本页记录不经常变化、所有维护者都需要知道的信息。Wiki 初始化完成后，Wiki 的 Project-Profile 是事实来源，本文件是只读镜像。

文档状态

线上 Gitea Wiki 已于 2026-08-20 初始化，15 个核心页面均已创建并回读确认。本页事实来源是 Wiki 的 Project-Profile，仓库中的 docs/00-project-profile.md 是只读镜像。长期文档的修改顺序固定为：修改 Wiki → 读取确认 → 导出 docs/ → 校验差异 → 提交镜像。不要直接编辑带 generated: true 头的本地文件。

基本信息

项目	内容
项目名称	chorus
一句话目标	提供独立于 cmhub 的 Go 生图生文服务：用户提交提示词与原图得到新图或文本，运营在管理端配置上游并查看记录
主要使用者	终端用户（Web 端生成）、运营与管理员（管理端）、Claude/Codex Agent、接手简单维护的初级程序员
Gitea 地址	https://git.ilapage.cn
仓库	`OPC/chorus`
默认分支	`main`
主要维护者	`ila`
需求来源	Obsidian 笔记《cmgen · 从 cmhub 抽取生图生文服务 — 需求与 Go 技术方案》（2026-08-20）；项目代号由 `cmgen` 改为 `chorus`
文档适用范围	默认分支当前版本

DevHarness 来源与基线

项目	内容
DevHarness 来源仓库	`https://git.ilapage.cn/OPC/dev_harness`
当前基线提交	`0b6ec7675dfc2d930a30527eddac83f4302d0879`
最后接入或升级日期	2026-08-26
项目适配说明	增量采用 Harness 规则、工单模板、Wiki 镜像与结构检查工具；`docs/00`、`02`–`06`、`09` 和 `docs/README.md` 按 Chorus 改写，`docs/01`、`07`、`08`、`delivery/`、`templates/` 沿用上游通用规则；保留 Chorus 项目红线和单人开发低风险直接提交边界

子项目与交付单元

子项目 / 交付单元	职责	技术栈与版本	构建与测试	发布方式	共享边界
`internal/core` 核心域库	领域模型、provider 协议抽象、生成编排、队列状态、加密接口	Go 1.26.5、GORM、标准库	`go test ./internal/core/...`	不单独发布	不得 import Gin、go-admin、gobreaker 或 imaging
`internal/platform` 基础设施适配	出站 HTTP/SSRF、熔断、图片处理、存储等接口实现	标准库、sony/gobreaker、disintegration/imaging	`go test ./internal/platform/...`	随服务二进制发布	通过接口注入 core，不反向污染领域层
`portal` 用户端二进制	会话、页面/HTMX 片段、JSON API，MVP 阶段内嵌 worker	Gin、html/template、HTMX、Alpine、Tailwind	`pnpm --dir portal/web build`、`go test ./portal/...`、浏览器 E2E	单二进制	依赖 core 与 platform；提交链路不得调用上游
`admin` 管理端后端	Provider、模型、Prompt、路由池、生成记录与终端用户只读查询	固定提交的 go-admin（Gin、GORM、Casbin、JWT）	`go -C admin test ./...`	独立二进制	嵌套 Go module；依赖 core；不得复制生成逻辑；项目不包含点数、余额或配额
`admin-ui` 管理端前端	go-admin-ui CRUD 与少量定制页	Vue 3.5.41、Element Plus 2.14.4、Vue CLI 5.0.9	`pnpm install --frozen-lockfile`、`pnpm build:prod`	静态产物	代码生成器只在隔离开发环境使用
`migrations` 数据库迁移	业务表、`sys_*` 基线和菜单/API 配置的全部生产演进	golang-migrate SQL	up/down 隔离库验证	随版本发布	生产数据库结构的唯一事实来源

管理员 sys_user 与终端用户 users 分表。MVP-0 只要求 core、platform、portal 和必要迁移可运行；admin/admin-ui 在 MVP-1 接入，但生产所需 sys_* 初始结构和配置仍必须先转成版本化 SQL。任何构建、CI 或部署都不得依赖 D:\github\goadmin 的绝对路径。

#23 已把固定 go-admin 的所需后端源导入 admin/ 这个嵌套 Go module，并把内部 import 改为仓库模块路径。运行入口是 admin/cmd/server.go；生产仅保留 chorus-admin server --config <受保护配置>，不导入原项目的 cmd/migrate、代码生成、Swagger、WebSocket 或静态文件路由。该入口只连接已经迁移的数据库，不执行 AutoMigrate、迁移或 seed。

技术栈与运行环境

固定来源基线

项目	本地审查来源	固定提交	关键约束
go-admin	`D:\github\goadmin\go-admin`	`f06540883b41d03782bb6b2c4150f298f328c6b6`	`go.mod` 要求 Go 1.26.5
go-admin-ui	`D:\github\goadmin\go-admin-ui`	`67d393d713877572fab0b897296a4c1d525fc81d`	Vue 3.5.41、Element Plus 2.14.4、Vue CLI 5.0.9、Node >=22、`packageManager=pnpm@9.15.1`
go-admin-doc	`D:\github\goadmin\go-admin-doc`	`424855aacf6905f3fde860c3331385cb25529a0d`	只作固定版本说明参考

这些路径用于审查和导入来源，不是运行依赖。首次接入必须把需要的脚手架/前端代码纳入 chorus 仓库或把 Go 依赖锁定到可复现版本，并在实现工单记录来源提交、导入范围和本地修改。

运行栈

部分	技术	说明
Go	1.26.5	以固定 go-admin 的 `go.mod` 为最低统一版本，不再使用原文档的 Go 1.22+
HTTP	Gin	portal 与 admin 共用生态，但 core 不依赖 Gin
ORM 与迁移	GORM + golang-migrate	GORM 负责运行期持久化；生产禁止 AutoMigrate
数据库	MySQL 8.0+；当前开发验收为 8.4.8	单库；队列依赖 `SELECT … FOR UPDATE SKIP LOCKED`
队列	MySQL 租约	不引入 Redis/MQ；租约 token + CAS 防止陈旧 worker 提交
管理端	固定 go-admin + go-admin-ui	schema-first 生成 CRUD；生产关闭 dev-tools
用户端会话	alexedwards/scs	Cookie 会话，不复用管理员 JWT
平台适配	gobreaker、imaging	只能位于 `internal/platform`
限流	ulule/limiter	MVP-2 用户维度令牌桶
上游调用	`net/http` 适配器	支持多图、`extra_body`、URL/Base64 差异，并实施 SSRF 钩子
用户端 UI	html/template + HTMX 2.x + Alpine 3.x + Tailwind 4.x	portal 运行时不需要 Node；重建 portal/web 与 admin-ui 静态资源需要 Node/pnpm
开发环境	Windows + PowerShell + Git；本机隔离 MySQL 8	Harness 使用 Python 3 标准库；Chorus 专用实例使用回环地址和独立端口/数据目录

已验证的 MVP-0 本机基线（2026-08-20）

Go 使用官方 Windows amd64 压缩包固定为 1.26.5；SHA-256 为 97e6b2a833b6d89f9ff17d25419ac0a7e3b482a044e9ab18cdef834bd834fd38。便携工具目录加入当前开发 Shell 的 PATH，不替换机器已有 Go。
golang-migrate 固定为 v4.19.1；Windows amd64 发布资产 SHA-256 为 d2537dfd991787c1e458965c4f49098c5a72f943bfc9d975c573a9c245f7ba2e。
开发数据库复用本机 MySQL 8.4.8 二进制，但使用 Chorus 专用数据目录、127.0.0.1:3308 和独立账号/库；现有 3307 实例和 MySQL 5.7 服务均不修改。
本机凭据由仓库外、仅当前账号可读的 PowerShell 环境文件注入；Wiki、工单、Git 和日志只记录变量名，不记录密码或完整 DSN。
已验证实例停止/重启、最小权限连接以及 SELECT ... FOR UPDATE SKIP LOCKED。这只证明开发环境可用，不代表生产部署已经验证。

AutoMigrate 与代码生成结论

go-admin 固定提交的 cmd/migrate 和模板中确有 AutoMigrate；它适合帮助理解脚手架初始化结构，但不是可审查、可回退的生产迁移。
如确需研究该初始化结果，只能由人工在隔离、可丢弃、无生产数据的开发数据库中单独运行，并把得到的结构差异整理为 migrations/*.up.sql 与 *.down.sql。
go-admin-ui 的生成器先从数据库导入已有表到 sys_tables/sys_columns，再生成 Go/Vue 文件；因此标准流程是先执行版本化 SQL，再导入和生成。
生成器的“生成迁移脚本”主要写菜单、权限与 API 配置的 Go 迁移代码，并不是业务表 DDL，也没有本项目要求的可逆性和幂等证据；这些配置必须人工转换为可逆 SQL。
dev-tools 路由包含写文件和写菜单的能力，固定提交中只有 JWT 保护且被 Casbin 排除，生产构建不得注册、代理或暴露这些路由。

阅读入口

新人入口：Home。
产品需求与 MVP 分期：产品需求总览。
代码入口：架构与代码地图。
业务边界：业务规则与术语。
运行验证：本地开发与验证。
简单维护：常见修改指南。
错误定位：故障排查。

常用命令

所有命令默认从仓库根目录执行。Windows 本地开发优先使用 #14 提供的受管启动脚本；脚本只封装已有构建与运行入口，不执行迁移、AutoMigrate 或 seed。

用途	命令	预期结果
查看工作区	`git status --short --branch`	显示分支且没有无关修改
检查文档结构	`python dev_scripts/harness.py check --strict`	输出“DevHarness 检查通过”
运行 Harness 测试	`python -m unittest discover -s tests -v`	所有测试通过
检查核心 Wiki 镜像	`python dev_scripts/harness.py sync --check`	Wiki 初始化后输出核心镜像一致
编译	`go build ./...`	无错误
单元测试	`go test ./...`	全部通过
静态检查	`go vet ./...`	无输出
管理端编译与测试	`go -C admin build .`、`go -C admin test ./...`	独立 admin module 无错误
数据库迁移	`migrate -path migrations -database "$CHORUS_MIGRATE_URL" up`	迁移版本前进且无错误
幂等种子	`go run ./cmd/chorus-seed`	只输出完成状态，不输出凭据
启动用户端	`scripts\chorus-dev.bat start`	后台启动并检查 `/login`，不执行迁移或 seed
查看本地进程	`scripts\chorus-dev.bat status`	显示受管 portal 和 mock 的状态、PID 与日志位置
停止本地进程	`scripts\chorus-dev.bat stop`	只停止脚本记录且路径匹配的进程

目录边界

目录	职责	不应放入
`internal/core/`	领域模型、协议接口、编排与状态规则	Gin、go-admin、gobreaker、imaging、HTTP handler
`internal/platform/`	HTTP/SSRF、熔断、图片、存储等适配器	页面、管理端 CRUD、业务状态机复制
`portal/`	用户端 Gin、模板、静态资源、worker 组装	直接实现 provider 选路和上游协议
`admin/`	go-admin 后端及 `app/chorus/`	绕过 core 的生成实现、生产代码生成路由
`admin-ui/`	固定 go-admin-ui 导入代码与定制页	运行时依赖 `D:\github\goadmin`
`migrations/`	全部生产表结构与配置种子 SQL	测试数据、AutoMigrate、不可逆一次性修数
`docs/`	核心长期文档的 Wiki 只读镜像	人工直接维护的最终事实
`docs/task/`	仅保存用户明确要求的专项或历史兼容 Wiki 任务快照	单次任务的默认证据和自动导出
`prototypes/`	按明确要求导出的工单/版本 HTML 原型快照；已有快照保留为历史证据	凭据、个人信息、生产数据
`scripts/`	Chorus 本地开发与运行辅助脚本	DevHarness 工具、凭据和生产数据
`dev_scripts/`	DevHarness 工具	产品业务脚本
`tests/`	Harness 测试；Go 测试与代码同目录	生产数据

环境、配置与凭据

核心 Wiki 同步配置是 wiki-docs.json；Gitea 地址可用 GITEA_URL 覆盖。
Gitea PAT 仅从进程环境、MCP 安全配置或本机未跟踪的环境文件加载，不写入仓库、工单或 Wiki。
数据库连接串由 CHORUS_DSN 提供。
Provider api_key 按用户已接受的风险决策明文保存在 provider_credentials.api_key；列表和普通详情只返回是否已配置，只有受 JWT/Casbin 保护的单 Provider 凭据接口可显式回显，且响应设置 Cache-Control: no-store 与 Pragma: no-cache。
会话签名/加密密钥仍由受保护配置提供；生产 Cookie 必须启用 Secure、HttpOnly 和合适的 SameSite。Provider 明文密钥不得进入代码、日志、审计、错误、工单、Wiki、原型或截图。
生成物默认落受保护的本地目录，不能直接把真实路径暴露为公开静态 URL；访问先校验用户归属。storage 从第一天是接口，预留 S3/OSS。
测试只用构造数据与 mock 上游；真实连通性检查必须是管理员明确触发的单次低成本动作，并有审计和冷却。
上传数量、单文件/总大小、允许 MIME、像素上限、上游超时、租约时长、保留期和限流阈值均为配置。未确认生产值前保持部署门禁，不由 Agent 臆造。

项目专用验收要求

长期核心文档必须先更新 Wiki，再导出本地镜像；Wiki 初始化未完成前，文档修改直接在 docs/ 进行并在工单说明。
python dev_scripts/harness.py check --strict 必须通过。
MVP-0 落地后：go build ./...、go vet ./...、go test ./... 必须通过。
涉及 retryable 判定、SSRF 校验、密钥加解密和迁移的修改必须有针对性单元测试。
未执行或无法覆盖的验证必须记录到工单。

MVP-0 完成状态（2026-08-21）

#5～#12 和 #14 已由用户验收；#13 集成验收执行中发现 #10 的内嵌 worker 未接入 portal/main.go，已用缺陷 #15 恢复既有确认行为。
当前候选版本已在本机 MySQL 8.4.8 隔离库完成空库 up/down/up、重复种子、Go build/vet/race、真实 portal 进程认领、Playwright 四视口和终态验证。
用户于 2026-08-21 明确确认 #4 验收通过；MVP-0 的全部单元任务、独立集成验收和父工单均已完成并归档。Epic #3 保持开启，后续 MVP 必须另行确认。
验证只使用构造用户、构造图片、mock 上游与测试 fixture；没有连接生产/共享库、调用真实 Provider 额度或发布生产。

Provider 凭据风险决策与 #24 已交付实现（2026-08-22）

用户已在 #30 明确接受 Provider API Key 明文落库及单条主动查看的风险。#24 已交付实现移除了运行时 CHORUS_MASTER_KEY 依赖，迁移 000005 在存在旧加密凭据时停止，禁止猜测或丢弃；列表和普通详情不返回完整密钥，单条读取禁止缓存。管理端使用固定 go-admin/go-admin-ui 基线，Casbin 显式读取迁移管理的 sys_casbin_rule 并关闭 adapter AutoMigrate。该实现已通过 MySQL 8、Go、前端构建和真实账号密码/API 联调，并于 2026-08-22 通过用户验收。

#38 统一本地服务启动入口（2026-08-24，验收通过）

Windows 本地开发可使用 config/local-services.yml 与 scripts/start-all.bat、status-all.bat、stop-all.bat 统一管理 Portal、Admin API 和 Admin UI。统一配置只保存 loopback Host、端口和受保护配置文件路径，不保存或复制 DSN、JWT secret、密码、Token 或 Provider Key。

Portal 的数据库、Session 等敏感配置仍来自 portal.environment_file 指向的受保护 PowerShell 环境文件；Provider/worker 运维参数来自 portal.settings_file 指向的严格 YAML，已设置的同名环境变量逐项覆盖 YAML。统一配置覆盖 CHORUS_LISTEN_ADDRESS 并传递两个 Portal 配置路径；Admin API 的 Host/Port 和敏感值仍以 admin.settings_file 为唯一事实源。脚本不会运行 migration、AutoMigrate、seed、管理员 bootstrap 或依赖安装。

统一脚本只管理状态文件记录且可执行路径匹配的进程。端口被未受管进程占用时显示 unmanaged listener 并拒绝接管；启动中途失败只回滚本次新启动的组件。现有 scripts/chorus-dev.bat 继续用于单独管理 Portal 和 mock。

#39 本机 Supervisor 三实例（2026-08-24，验收通过）

本机 D:\supervisor 通过 scripts/install-supervisor.bat 安装并托管三个独立实例：chorus-user、chorus-admin-api、chorus-admin-ui。Portal 地址、环境文件和 YAML settings 路径来自 config/local-services.yml；Admin API 地址与运行配置来自 admin/config/settings.yml。安装器只把构建产物和配置路径写入 Supervisor 目录，Portal 启动时才在进程内读取受保护文件。

三个实例均以前台子进程运行，启用自动重启、独立日志和进程组停止。更新代码或统一配置后重新运行安装器，再执行 Supervisor reload。此入口只用于当前 Windows 本地环境，不执行 migration、AutoMigrate、seed 或账号创建。

#38 与 #39 已由用户于 2026-08-24 明确验收通过。