137 lines
4.8 KiB
Markdown
137 lines
4.8 KiB
Markdown
# 本地开发快速上手
|
||
|
||
本页用于日常开发：初始化依赖、迁移数据库、启动 API/Worker/平台前端并完成基础验证。若要从空数据库验收“创建租户 → Owner 激活 → 发布站点”的完整流程，请改看[空数据库到租户建站验收](tenant-provisioning.md)。
|
||
|
||
## 前置依赖
|
||
|
||
- .NET 10 SDK
|
||
- Node.js 24+、npm 11+
|
||
- PostgreSQL
|
||
- Redis（Development 可不配置；涉及分布式缓存、频控或完整验收时应启动）
|
||
|
||
```bash
|
||
dotnet --version
|
||
node --version
|
||
npm --version
|
||
pg_isready -h 127.0.0.1 -p 5432
|
||
```
|
||
|
||
首次拉取代码后恢复依赖：
|
||
|
||
```bash
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
npm --prefix Tiku.PlatformAdmin.Web install
|
||
```
|
||
|
||
## 配置数据库
|
||
|
||
Development 未配置连接串时，默认使用当前系统用户连接本机 `tiku` 数据库：
|
||
|
||
```text
|
||
Host=localhost;Database=tiku;Username=<当前系统用户>
|
||
```
|
||
|
||
首次使用可创建数据库：
|
||
|
||
```bash
|
||
createdb -h 127.0.0.1 -U <数据库用户> tiku
|
||
```
|
||
|
||
使用其他地址、端口或账号时，通过环境变量覆盖：
|
||
|
||
```bash
|
||
export ConnectionStrings__Database='Host=127.0.0.1;Port=5432;Database=tiku;Username=<数据库用户>;Password=<本地密码>'
|
||
```
|
||
|
||
不要把连接串、密码、Token 或私钥写入仓库。
|
||
|
||
## 迁移与初始化
|
||
|
||
API 不执行 Migration。数据库结构、内置权限/菜单目录和 `starter` 套餐统一由 `Tiku.DbMigrator` 初始化：
|
||
|
||
```bash
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
|
||
```
|
||
|
||
默认 Development seed 会在尚无平台角色绑定时创建 `admin@tiku.local`、演示租户和演示运营数据；随机临时密码只在首次创建时输出，首次登录必须改密。
|
||
|
||
若需要不含演示数据的空库，使用显式 Bootstrap 流程，不要运行默认 Development seed：
|
||
|
||
```bash
|
||
export ASPNETCORE_ENVIRONMENT=Development
|
||
export TIKU_BOOTSTRAP_PLATFORM_ADMIN_EMAIL='<平台管理员邮箱>'
|
||
export TIKU_BOOTSTRAP_PLATFORM_ADMIN_PASSWORD='<临时密码>'
|
||
export TIKU_BOOTSTRAP_PLATFORM_ADMIN_NAME='<显示名称>'
|
||
|
||
dotnet run --project Tiku.DbMigrator -- \
|
||
--skip-development-seed \
|
||
--bootstrap-platform-admin
|
||
```
|
||
|
||
完整空库验收步骤见[空数据库到租户建站验收](tenant-provisioning.md)。
|
||
|
||
## 启动运行时
|
||
|
||
启动 API：
|
||
|
||
```bash
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Api --launch-profile http
|
||
```
|
||
|
||
`Tiku.Api.csproj` 的 SPA Proxy 会在 Development 启动 `Tiku.PlatformAdmin.Web` 的 Vite 服务。默认入口：
|
||
|
||
- 平台管理端：<http://localhost:5173>
|
||
- API：<http://localhost:5090>
|
||
- Scalar：<http://localhost:5090/scalar/v1>
|
||
- OpenAPI：<http://localhost:5090/openapi/v1.json>
|
||
- Liveness：<http://localhost:5090/api/system/health>
|
||
- Readiness：<http://localhost:5090/api/system/health/ready>
|
||
|
||
后台循环不在 API 内运行。需要处理域名、订阅、任务队列、授权缓存失效或商业账务时，另开终端启动 Worker：
|
||
|
||
```bash
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Worker
|
||
```
|
||
|
||
如需 Redis，API 与 Worker 应使用同一实例：
|
||
|
||
```bash
|
||
export ConnectionStrings__Redis='localhost:6379,abortConnect=false'
|
||
```
|
||
|
||
## 验证修改
|
||
|
||
```bash
|
||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||
dotnet test TIKU-BACKEND.slnx --no-build
|
||
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore
|
||
npm --prefix Tiku.PlatformAdmin.Web run check
|
||
dotnet ef migrations has-pending-model-changes \
|
||
--project Tiku.Infrastructure \
|
||
--startup-project Tiku.DbMigrator \
|
||
--no-build
|
||
git diff --check
|
||
```
|
||
|
||
PostgreSQL 特有的 Migration、事务、约束和租户隔离行为必须由真实 PostgreSQL 集成测试验证，EF InMemory 不能替代。接口、DTO 和错误响应以当前运行时 OpenAPI/Scalar 为准。
|
||
|
||
## 常见问题
|
||
|
||
### API 报数据库不可用
|
||
|
||
确认 PostgreSQL 已启动、数据库存在，并核对 `ConnectionStrings__Database` 或 `DATABASE_URL`。非 Development 环境没有本地默认连接串。
|
||
|
||
### 找不到平台管理员临时密码
|
||
|
||
默认 Development seed 和显式 Bootstrap 都只在创建账号时输出一次临时密码，后续运行不会重放。不要从日志或数据库恢复明文；应通过受控流程重置，或在确认无需保留本地数据后重建开发数据库。
|
||
|
||
### Readiness 返回 503
|
||
|
||
`/api/system/health/ready` 会检查 PostgreSQL 和已配置的 Redis。先验证数据库连接；配置 Redis 后还需确认 Redis 可访问。匿名响应不会暴露依赖详情。
|
||
|
||
### API 启动了但后台任务不执行
|
||
|
||
Production 和常规 Development 都需要独立运行 `Tiku.Worker`。Development 仅额外在 API 中注册本地域名生命周期旁路，不代表 API 承载全部 Worker 循环。
|
||
|
||
下一步可阅读[系统架构与业务边界](architecture/overview.md)、[认证、授权与租户隔离](architecture/security-and-tenancy.md)和[配置与后台任务](operations.md)。
|