架构总览¶

本仓库包含多个 Python 包与前端应用，通过 Kustomize 在 K3s / ACK 上组成 harness-app 全栈。

包 / 应用	端口	说明
`backend`	8001	主 API（代理商 + Canvas 生图 + 用户计费）
`storage`	8002	OSS 上传/下载微服务（AK 隔离）
`backend-worker`	—	Redis Stream 消费者（短信、生图队列）
`messaging`	—	独立消息库，不含 HTTP
`commons`	—	后端共享工具（HTTP 客户端、日志、请求上下文）
`infinitecanvas`	5173（dev）	用户前台（Infinite Canvas / 无限二创）
`agent-system`	5174（dev）	代理商前端
`admin-system`	5175（dev）	Canvas Admin 运营后台
`chat`	5178（dev）	图现 Chat（对接 Hermes）
`demo`	5177（dev）	C 端 Prompt 生图体验

端口以各应用 vite.config.ts / Settings.port 为准。harness.yaml 中仍保留 myapp（8000）条目属历史残留（src/myapp/ 已并入 backend），部署相关清理见技术债。

前端职责与路由详见前端应用总览、Infinite Canvas 前台；本地开发见前端开发 Runbook。

分层结构（单包内）¶

api/           → HTTP 路由层（FastAPI Router）
composition/   → 组合根 / 依赖注入（FastAPI Depends）
core/          → 业务逻辑层（Service）
db/            → 数据访问层（Repository + ORM）
schemas/       → Pydantic 请求/响应模型
utils/         → 横切关注点（日志、HTTP 客户端、遥测）

依赖规则（import-linter 强制）¶

源模块	禁止直接导入	说明
`myapp.api`	`myapp.db`	通过 `composition/` 间接注入
`myapp.core`	`myapp.api`
`myapp.db`	`myapp.api`, `myapp.core`
`messaging`	`backend`, `myapp`	独立消息包，由 composition wiring

消息组件（messaging）¶

基于 Redis Stream 的发布订阅，详见 messaging.md。

messaging/streams/     → XADD / XREADGROUP 发布与消费
messaging/workers/     → 短信 Worker、SSE Hub
backend/composition/   → SMS 分发与 Worker 启动

K8s 中 backend-worker Deployment 独立进程消费 Stream；Init 容器等待 Redis 就绪。详见 messaging.md。

OSS 存储（storage）¶

backend 不持有 OSS 密钥，经 HTTP 调用 storage 微服务。详见 storage.md。

技术栈¶

类别	技术
Web 框架	FastAPI + Uvicorn/Gunicorn
依赖管理	Poetry
代码质量	Ruff + mypy + Bandit
架构约束	import-linter + pytest-archon
测试	pytest + testcontainers + respx
可观测性	Prometheus + Loki + Grafana + OpenTelemetry
安全	pip-audit + gitleaks + Dependabot/Renovate
文档	MkDocs + ADR

可观测性¶

指标：GET /metrics（Prometheus 格式）
健康检查：GET /health/live、GET /health/ready
日志：JSON 结构化输出（python-json-logger），由 Promtail 采集至 Loki
追踪：OpenTelemetry OTLP → Tempo

启动观测栈：

docker compose -f observability/docker-compose.yml up -d