4.9 KiB
本地开发与运行
本页用于从全新开发环境启动当前 TIKU Backend。数据库迁移由 DbMigrator 执行，API 不会自动创建或更新 schema。
1. 准备环境
必需：
- .NET 10 SDK；
- PostgreSQL；
psql、createdb等 PostgreSQL 命令行工具。
可选：
- Redis 7；
- RabbitMQ 4。
dotnet --version
pg_isready -h 127.0.0.1 -p 5432
psql --version
2. 还原并构建
git clone <repository-url> TIKU-BACKEND
cd TIKU-BACKEND
dotnet restore TIKU-BACKEND.slnx
dotnet build TIKU-BACKEND.slnx --no-restore
3. 创建 PostgreSQL 数据库
当前系统用户能本地登录 PostgreSQL 时：
createdb -h 127.0.0.1 -U "$(whoami)" tiku
Development 未显式配置连接串时，API、DbMigrator 和设计时 EF 工具默认使用：
Host=localhost;Database=tiku;Username=<当前系统用户>
其他用户、端口或认证方式使用环境变量：
export DATABASE_URL='Host=127.0.0.1;Port=5432;Database=tiku;Username=<数据库用户>;Password=<本地密码>'
不要把含密码的连接串写入 appsettings*.json、README 或 Git。
4. 执行迁移和 seed
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
DbMigrator 会：
- 执行所有 EF Core Migration；
- seed 内置 Feature、Permission、菜单和额度目录；
- 在全新 Development 数据库创建平台超级管理员。
账号：admin@tiku.local
密码：首次创建时随机生成，只在当前终端输出一次
重复运行是幂等的，不会重置密码或再次显示临时密码。首次登录必须改密；不要为了找回密码删除已有业务数据的数据库。
Migration 需要 citext、ltree 和 pg_trgm 扩展。执行迁移的 PostgreSQL 用户必须有创建扩展的权限，或由管理员预先安装。
5. 启动 API
dotnet run --project Tiku.Api
默认 Development 入口：
- 平台管理端：http://localhost:5090/platform-admin/
- Scalar：http://localhost:5090/scalar/v1
- OpenAPI JSON：http://localhost:5090/openapi/v1.json
- Liveness：http://localhost:5090/api/health
- Readiness：http://localhost:5090/api/health/ready
OpenAPI 和 Scalar 仅在 Development 映射。接口路径、输入字段、响应模型和授权要求以这里生成的文档为准。
6. 可选：启动 Redis 和 RabbitMQ
本地单实例开发可以不配置这两个依赖。需要验证分布式安全频控、Output Cache、消息和 Outbox 时，先启动本地服务，再设置：
export ConnectionStrings__Redis='localhost:6379,abortConnect=false'
export RabbitMq__Host='rabbitmq://localhost'
export RabbitMq__VirtualHost='/'
export RabbitMq__Username='guest'
export RabbitMq__Password='guest'
RabbitMQ 使用 4.x，当前代码不依赖 delayed-message 插件。延时任务由 PostgreSQL RunAfter 调度。
7. 可选：启动 Worker
需要处理域名、订阅、用量或后台任务时，在另一个终端使用相同配置启动：
dotnet run --project Tiku.Worker
Worker 会立即开始轮询。域名 DNS/TLS 流程只有在 TenantDomains 的 CNAME target 和 Gateway 配置完整后才能激活自定义域名。
8. 开发验证
curl --fail http://localhost:5090/api/health
curl --fail http://localhost:5090/api/health/ready
dotnet test TIKU-BACKEND.slnx --no-build
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore
dotnet ef migrations has-pending-model-changes \
--project Tiku.Infrastructure \
--startup-project Tiku.DbMigrator \
--no-build
git diff --check
Tiku.IntegrationTests 会创建临时 PostgreSQL 数据库，验证 API、授权、迁移和租户隔离。测试账户和测试数据库只用于自动化验证。
常见问题
连接 PostgreSQL 失败
pg_isready -h 127.0.0.1 -p 5432
psql -h 127.0.0.1 -U <数据库用户> -d postgres -c 'select current_user;'
确认当前终端的 DATABASE_URL 指向真实存在的数据库，并且 API、DbMigrator 和 Worker 使用同一连接配置。
无法创建 PostgreSQL 扩展
请让数据库管理员安装 citext、ltree、pg_trgm，或授予迁移用户创建这些扩展所需的权限。
没看到管理员临时密码
临时密码只在全新 Development 数据库第一次创建管理员时显示。已有管理员时 DbMigrator 会跳过；应使用正常密码恢复流程。
Readiness 返回 503
检查响应中的 database、redis.ready 和 rabbitMq.ready。只配置了 Redis/RabbitMQ 连接串但服务未启动时，readiness 会按已配置依赖检查并返回 503。
API 出现 HTTPS 重定向警告
仅使用 HTTP launch profile 时可能无法确定 HTTPS 端口，不影响 http://localhost:5090 的本地访问。需要验证 HTTPS 时使用项目的 https profile。
更多配置见配置与后台任务，安全边界见认证、授权与租户隔离。