159 lines
5.4 KiB
Markdown
159 lines
5.4 KiB
Markdown
# 本地开发与运行
|
||
|
||
本页用于从全新开发环境启动当前 TIKU Backend。数据库迁移由 DbMigrator 执行，API 不会自动创建或更新 schema。
|
||
|
||
## 1. 准备环境
|
||
|
||
必需：
|
||
|
||
- .NET 10 SDK；
|
||
- PostgreSQL；
|
||
- `psql`、`createdb` 等 PostgreSQL 命令行工具。
|
||
|
||
可选：
|
||
|
||
- Redis 7；
|
||
- ClamAV（验证资源安全扫描时需要）。
|
||
|
||
```bash
|
||
dotnet --version
|
||
pg_isready -h 127.0.0.1 -p 5432
|
||
psql --version
|
||
```
|
||
|
||
## 2. 还原并构建
|
||
|
||
```bash
|
||
git clone <repository-url> TIKU-BACKEND
|
||
cd TIKU-BACKEND
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||
```
|
||
|
||
## 3. 创建 PostgreSQL 数据库
|
||
|
||
当前系统用户能本地登录 PostgreSQL 时：
|
||
|
||
```bash
|
||
createdb -h 127.0.0.1 -U "$(whoami)" tiku
|
||
```
|
||
|
||
Development 未显式配置连接串时，API、DbMigrator 和设计时 EF 工具默认使用：
|
||
|
||
```text
|
||
Host=localhost;Database=tiku;Username=<当前系统用户>
|
||
```
|
||
|
||
其他用户、端口或认证方式使用环境变量：
|
||
|
||
```bash
|
||
export DATABASE_URL='Host=127.0.0.1;Port=5432;Database=tiku;Username=<数据库用户>;Password=<本地密码>'
|
||
```
|
||
|
||
不要把含密码的连接串写入 `appsettings*.json`、README 或 Git。
|
||
|
||
## 4. 执行迁移和 seed
|
||
|
||
```bash
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
|
||
```
|
||
|
||
DbMigrator 会：
|
||
|
||
1. 执行所有 EF Core Migration；
|
||
2. seed 内置 Feature、Permission、菜单和额度目录；
|
||
3. 在全新 Development 数据库创建平台超级管理员。
|
||
|
||
```text
|
||
账号：admin@tiku.local
|
||
密码：首次创建时随机生成，只在当前终端输出一次
|
||
```
|
||
|
||
重复运行是幂等的，不会重置密码或再次显示临时密码。首次登录必须改密；不要为了找回密码删除已有业务数据的数据库。
|
||
|
||
Migration 需要 `citext`、`ltree` 和 `pg_trgm` 扩展。执行迁移的 PostgreSQL 用户必须有创建扩展的权限，或由管理员预先安装。
|
||
|
||
## 5. 启动 API
|
||
|
||
```bash
|
||
dotnet run --project Tiku.Api
|
||
```
|
||
|
||
默认 Development 入口：
|
||
|
||
- 平台管理端：首次在 `Tiku.PlatformAdmin.Web` 执行 `npm install`；之后启动 `Tiku.Api` 时会在 Development 自动启动前端，访问 <http://localhost:5173>
|
||
- 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
|
||
|
||
本地单实例开发可以不配置 Redis。需要验证安全频控、Feature 缓存和 Output Cache 时，先启动本地服务，再设置：
|
||
|
||
```bash
|
||
export ConnectionStrings__Redis='localhost:6379,abortConnect=false'
|
||
```
|
||
|
||
Production 必须配置 Redis；PostgreSQL 仍是用户、Session、权限、套餐和用量的权威数据源。
|
||
|
||
## 7. 启动 Worker 与 ClamAV
|
||
|
||
API 不处理后台循环。另开终端启动 Worker：
|
||
|
||
```bash
|
||
dotnet run --project Tiku.Worker
|
||
```
|
||
|
||
`Worker__Enabled=false` 仅用于测试或维护。后台任务状态、租约、重试和 `RunAfter` 存在 PostgreSQL；多个 Worker 通过 advisory lock 和任务租约协调。域名 DNS/TLS 流程只有在 `TenantDomains` 的 CNAME target 和 Gateway 配置完整后才能激活自定义域名。
|
||
|
||
上传确认会创建 `asset_security_scan` 任务。Worker 通过 TCP 3310 连接 ClamAV，且 ClamAV `StreamMaxLength` 必须不小于 `Storage:MaxUploadBytes`（当前默认均为 500 MiB）。本地可以使用容器启动 ClamAV，并确保该限制已配置；ClamAV 不可用时任务会重试，资源保持不可访问。
|
||
|
||
## 8. 开发验证
|
||
|
||
```bash
|
||
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 失败
|
||
|
||
```bash
|
||
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 使用同一连接配置。
|
||
|
||
### 无法创建 PostgreSQL 扩展
|
||
|
||
请让数据库管理员安装 `citext`、`ltree`、`pg_trgm`，或授予迁移用户创建这些扩展所需的权限。
|
||
|
||
### 没看到管理员临时密码
|
||
|
||
临时密码只在全新 Development 数据库第一次创建管理员时显示。已有管理员时 DbMigrator 会跳过；应使用正常密码恢复流程。
|
||
|
||
### Readiness 返回 503
|
||
|
||
匿名 readiness 只返回总体 `status` 与 `checkedAt`。配置了 Redis 连接串但服务未启动时会返回 503；依赖细节需要使用具有 `platform:operations:view` 权限的平台账号访问 `/api/platform-admin/operations/health`。
|
||
|
||
### API 出现 HTTPS 重定向警告
|
||
|
||
仅使用 HTTP launch profile 时可能无法确定 HTTPS 端口，不影响 `http://localhost:5090` 的本地访问。需要验证 HTTPS 时使用项目的 `https` profile。
|
||
|
||
更多配置见[配置与后台任务](operations.md)，安全边界见[认证、授权与租户隔离](architecture/security-and-tenancy.md)。
|