跳转至

新手上手指南

面向第一次接触本项目的测试与新成员。跟着做能把整套环境跑起来并看到数据。 账号信息线下提供，本文不含任何手机号/密码。功能全景见 产品需求总览。

1. 环境准备

依赖 版本 说明
Python 3.12 见 .python-version
Node 22 见 src/agent-system/.node-version
Poetry 最新 后端依赖管理
pnpm 最新 前端依赖管理
Docker Desktop 可选 仅 make up / make docs-up 需要；纯本地用 make run-backend 不需要
PostgreSQL 15+ 本地用 Docker（端口 5433）或直装
Redis 7+ 本地用 Docker（端口 6380）或直装

Windows 推荐 Rancher Desktop（K3s 全栈）或 Docker Desktop；macOS/Linux 任一即可。

2. 标准启动序列

按依赖顺序执行（每步说明产出）：

# ① 安装依赖（后端 Poetry + 前端 pnpm）
make install

# ② 安装 git 质量门禁钩子（16 项 pre-commit）
poetry run pre-commit install
poetry run pre-commit install --hook-type commit-msg

# ③ 启动基础设施 + 后端 + 前端（按 harness.yaml 拓扑）
make up
# 等价于：postgres → redis → backend → storage → canvas/agent/admin

# ④ 执行数据库迁移（含会员 7 档方案 + 分账规则数据迁移）
make backend-migrate

# ⑤ 播种业务字典数据（产品树/面料/模型池/模板/模特属性/视频样本）
make backend-seed-v3

# ⑥ 创建可登录测试账号 + 示例画布项目（账号线下获取）
make seed

# ⑦ 冒烟验证：health check + API 探活
make smoke

# ⑧ 查看各服务端口与 PID
make ps

一键重置（慎用，清空 dev 数据）：make reset = down → 清库 → migrate → up → seed。 注意 make reset 不跑 backend-seed-v3，需手动补。

3. 种子数据清单

make backend-migrate 写入（Alembic 数据迁移）

  • 会员方案 7 档（体验/基础/进阶/专业/企业/旗舰/至尊）—— s1f2a3b4c5d6_seed_membership_tiers_v1
  • 代理分账规则（一级/二级档位）—— 同上迁移
  • 不在 seed 里：上线后改价/改佣金走 Admin 或新 Alembic data migration

make backend-seed-v3 写入（业务字典）

数据 说明
产品大类 / 子类 从 tuxian_tree_split.json 解析，含层级
面料类型 / 面料材质 及子类↔材质关联（按 applicable_functions 笛卡尔积）
系统配置 分辨率/比例/质量/定价/prompt 前缀等
AI 模型 + API Key 智能图片模型 + RunningHub 视频模型
模型池（10 个默认池） virtual_studio / main_image / detail_image / hot_replicate 等
视频样本提示词组 种草 + 剧情各 1 组
模特生成属性（134 条） 性别/年龄/国籍/体型/脸型/五官/妆容/发型/发色 等
超级管理员 1 条（账号线下给）

make seed 写入（测试账号 + 项目）

  • 可登录测试用户（账号线下给）
  • 示例画布项目

4. 各端访问地址

端 地址 登录
用户画布 http://127.0.0.1:5173 用户短信登录
代理商 http://127.0.0.1:5174 代理登录（as_agent）
Canvas Admin http://127.0.0.1:5175 管理员短信登录
Chat http://127.0.0.1:5178 对接 Hermes
Backend API http://127.0.0.1:8001 —
Backend Swagger http://127.0.0.1:8001/docs —
Storage http://127.0.0.1:8002 —
文档站 http://127.0.0.1:8003 make docs-serve

前端 Vite 代理已把 /api → localhost:8001，无需额外配置。

5. 各服务独立启动（调试用）

make run-backend    # 仅后端 :8001（需先起 postgres/redis）
make run-storage    # 仅 storage :8002
make canvas-dev     # 仅画布 :5173
make agent-dev      # 仅代理 :5174
make admin-dev      # 仅 admin :5175
make docs-serve     # 仅文档站 :8003

6. 常见问题

问题 原因 解决
make docs-up 报 dockerDesktopLinuxEngine Docker Desktop 未启动 用 make docs-serve 免 Docker，或启动 Docker Desktop
端口被占用 上次服务未关 make ps 查 PID，make down 或手动 kill
前端登录提示 CORS backend CORS_ORIGINS 未含前端源 检查 src/backend/.env 的 CORS_ORIGINS
画布生图 402 配额不足 未购买方案或配额用尽 账号中心购买方案（mock 支付），或 Admin 调配额
上传报「存储空间不足」 超出会员 storage_gb 换更高档方案，或 Admin 调配额
模板/产品树为空 未跑 backend-seed-v3 执行 make backend-seed-v3
会员方案为空 未跑迁移 执行 make backend-migrate
make reset 后数据不全 reset 不补 backend-seed-v3 手动补 make backend-seed-v3
backend-worker 卡住 等 Redis 就绪 确认 Redis 已起（make ps）；就绪后自动启动

7. 质量门禁（提交前）

make check          # 后端全门禁
make admin-check    # admin 前端
make agent-check    # agent 前端
canvas-check        # canvas 前端（typecheck + build + test）
pre-commit run --all-files   # 16 项 hook 全量自检

提交信息须符合 conventional commits（feat: / fix: 等），见 pre-commit 手册。

8. 下一步