docs: rewrite documentation from current implementation
This commit is contained in:
@@ -1,40 +1,19 @@
|
||||
# 本地开发快速开始
|
||||
# 本地开发与运行
|
||||
|
||||
## 可选分布式依赖
|
||||
|
||||
本地单实例开发可以不配置 Redis/RabbitMQ，认证频控仍保留 PostgreSQL/进程内防线；Production 两者均为启动必填项。
|
||||
|
||||
```bash
|
||||
export ConnectionStrings__Redis='localhost:6379,abortConnect=false'
|
||||
export RabbitMq__Host='rabbitmq://localhost'
|
||||
export RabbitMq__Username='guest'
|
||||
export RabbitMq__Password='guest'
|
||||
```
|
||||
|
||||
RabbitMQ 使用 MassTransit 8.5.10 和 PostgreSQL EF Bus/Consumer Outbox。`GET /api/health` 是 liveness，`GET /api/health/ready` 检查 PostgreSQL、已配置的 Redis、RabbitMQ bus health，并返回 outbox pending、最老消息时长和阈值告警；服务健康不等于认证授权验收完成。
|
||||
官方 RabbitMQ 4.x 镜像无需安装 delayed-message 插件；不要配置 `UseDelayedRedelivery`，延时后台任务由 PostgreSQL `RunAfter` 调度。
|
||||
|
||||
本地 Broker 重启/outbox 恢复演练（仅对明确指定的测试容器执行 stop/start）：
|
||||
|
||||
```bash
|
||||
TIKU_TEST_RABBITMQ=rabbitmq://localhost \
|
||||
TIKU_TEST_RABBITMQ_RESTART=1 \
|
||||
TIKU_TEST_RABBITMQ_CONTAINER=tiku-rabbitmq \
|
||||
dotnet test Tiku.IntegrationTests/Tiku.IntegrationTests.csproj \
|
||||
--filter 'FullyQualifiedName~Bus_outbox_drains_after_real_broker_restart'
|
||||
```
|
||||
|
||||
这份文档用于从全新开发环境启动 TIKU Backend、初始化 PostgreSQL，并完成平台管理员的首次登录。
|
||||
本页用于从全新开发环境启动当前 TIKU Backend。数据库迁移由 DbMigrator 执行，API 不会自动创建或更新 schema。
|
||||
|
||||
## 1. 准备环境
|
||||
|
||||
需要安装：
|
||||
必需：
|
||||
|
||||
- .NET 10 SDK；
|
||||
- PostgreSQL（当前本地开发已验证 PostgreSQL 18）；
|
||||
- PostgreSQL；
|
||||
- `psql`、`createdb` 等 PostgreSQL 命令行工具。
|
||||
|
||||
确认工具可用：
|
||||
可选：
|
||||
|
||||
- Redis 7；
|
||||
- RabbitMQ 4。
|
||||
|
||||
```bash
|
||||
dotnet --version
|
||||
@@ -42,7 +21,7 @@ pg_isready -h 127.0.0.1 -p 5432
|
||||
psql --version
|
||||
```
|
||||
|
||||
## 2. 获取并还原项目
|
||||
## 2. 还原并构建
|
||||
|
||||
```bash
|
||||
git clone <repository-url> TIKU-BACKEND
|
||||
@@ -51,78 +30,95 @@ dotnet restore TIKU-BACKEND.slnx
|
||||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||||
```
|
||||
|
||||
## 3. 创建本地数据库
|
||||
## 3. 创建 PostgreSQL 数据库
|
||||
|
||||
如果本机 PostgreSQL 允许当前系统用户无密码登录，可以直接执行：
|
||||
当前系统用户能本地登录 PostgreSQL 时：
|
||||
|
||||
```bash
|
||||
createdb -h 127.0.0.1 -U "$(whoami)" tiku
|
||||
```
|
||||
|
||||
Development 环境未显式配置连接串时，API 和 DbMigrator 默认使用：
|
||||
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=<本地密码>'
|
||||
```
|
||||
|
||||
不要把包含密码的连接串写进 README、`appsettings*.json` 或提交到 Git。团队成员应各自使用环境变量、.NET Secret Manager 或受控密钥存储。
|
||||
不要把含密码的连接串写入 `appsettings*.json`、README 或 Git。
|
||||
|
||||
## 4. 执行迁移并初始化管理员
|
||||
## 4. 执行迁移和 seed
|
||||
|
||||
```bash
|
||||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
|
||||
```
|
||||
|
||||
DbMigrator 会执行全部 EF Core Migration，并在全新 Development 数据库中自动创建平台超级管理员：
|
||||
DbMigrator 会：
|
||||
|
||||
1. 执行所有 EF Core Migration；
|
||||
2. seed 内置 Feature、Permission、菜单和额度目录；
|
||||
3. 在全新 Development 数据库创建平台超级管理员。
|
||||
|
||||
```text
|
||||
账号：admin@tiku.local
|
||||
密码：首次初始化时安全随机生成，只在当前终端输出一次
|
||||
密码：首次创建时随机生成，只在当前终端输出一次
|
||||
```
|
||||
|
||||
请立即保存终端显示的临时密码。重复执行 DbMigrator 是幂等的，不会重复创建管理员、重置密码或再次显示密码。
|
||||
重复运行是幂等的，不会重置密码或再次显示临时密码。首次登录必须改密；不要为了找回密码删除已有业务数据的数据库。
|
||||
|
||||
管理员首次登录后必须修改临时密码。正式密码至少 8 位，并同时包含字母和数字；平台管理员当前使用账号和密码登录，不要求绑定认证器。
|
||||
Migration 需要 `citext`、`ltree` 和 `pg_trgm` 扩展。执行迁移的 PostgreSQL 用户必须有创建扩展的权限，或由管理员预先安装。
|
||||
|
||||
普通租户用户以手机号作为账号，可以使用手机号和密码登录，也可以使用手机号和短信验证码登录。
|
||||
|
||||
如果数据库已经包含平台管理员，自动初始化会跳过。不要为了重新获取密码删除包含业务数据的数据库。
|
||||
|
||||
## 5. 启动 API 和平台后台
|
||||
## 5. 启动 API
|
||||
|
||||
```bash
|
||||
dotnet run --project Tiku.Api
|
||||
```
|
||||
|
||||
默认开发地址：
|
||||
默认 Development 入口：
|
||||
|
||||
- 平台后台：<http://localhost:5090/platform-admin/>
|
||||
- Scalar API 文档：<http://localhost:5090/scalar/v1>
|
||||
- 平台管理端：<http://localhost:5090/platform-admin/>
|
||||
- Scalar：<http://localhost:5090/scalar/v1>
|
||||
- OpenAPI JSON：<http://localhost:5090/openapi/v1.json>
|
||||
- 健康检查：<http://localhost:5090/api/health>
|
||||
- Liveness：<http://localhost:5090/api/health>
|
||||
- Readiness：<http://localhost:5090/api/health/ready>
|
||||
|
||||
平台后台默认连接同源真实 API，不会回退到 Mock 数据。当前开放的是已有后端契约的概览、租户、员工、审计和告警等页面；尚未接入真实接口的模块暂不开放。
|
||||
OpenAPI 和 Scalar 仅在 Development 映射。接口路径、输入字段、响应模型和授权要求以这里生成的文档为准。
|
||||
|
||||
## 6. 可选：启动 Worker
|
||||
## 6. 可选：启动 Redis 和 RabbitMQ
|
||||
|
||||
需要调试后台任务时，另开终端并使用相同数据库连接：
|
||||
本地单实例开发可以不配置这两个依赖。需要验证分布式安全频控、Output Cache、消息和 Outbox 时，先启动本地服务，再设置：
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
需要处理域名、订阅、用量或后台任务时，在另一个终端使用相同配置启动：
|
||||
|
||||
```bash
|
||||
dotnet run --project Tiku.Worker
|
||||
```
|
||||
|
||||
普通 API 开发不要求同时启动 Worker。
|
||||
Worker 会立即开始轮询。域名 DNS/TLS 流程只有在 `TenantDomains` 的 CNAME target 和 Gateway 配置完整后才能激活自定义域名。
|
||||
|
||||
## 7. 开发前验证
|
||||
## 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 \
|
||||
@@ -132,29 +128,33 @@ dotnet ef migrations has-pending-model-changes \
|
||||
git diff --check
|
||||
```
|
||||
|
||||
PostgreSQL 特有的 Migration、约束、事务和租户隔离行为必须使用真实 PostgreSQL 验证，不能只依赖 EF InMemory 测试。
|
||||
`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` 指向正确的主机、端口、数据库和用户。
|
||||
确认当前终端的 `DATABASE_URL` 指向真实存在的数据库，并且 API、DbMigrator 和 Worker 使用同一连接配置。
|
||||
|
||||
### 首次迁移无法创建扩展
|
||||
### 无法创建 PostgreSQL 扩展
|
||||
|
||||
Migration 会创建 `citext` 和 `ltree` 扩展。初始化数据库的 PostgreSQL 用户必须有安装这些扩展所需的权限；请让本地数据库管理员预先安装扩展或授予对应权限。
|
||||
请让数据库管理员安装 `citext`、`ltree`、`pg_trgm`，或授予迁移用户创建这些扩展所需的权限。
|
||||
|
||||
### 没看到管理员临时密码
|
||||
|
||||
临时密码只在全新 Development 数据库首次创建管理员时显示。如果管理员绑定已经存在，迁移会安全跳过。请使用已有管理员账号的密码恢复流程，不要在源码或文档中添加固定密码。
|
||||
临时密码只在全新 Development 数据库第一次创建管理员时显示。已有管理员时 DbMigrator 会跳过；应使用正常密码恢复流程。
|
||||
|
||||
### API 启动后出现 HTTPS 重定向警告
|
||||
### Readiness 返回 503
|
||||
|
||||
本地仅使用 HTTP profile 时可能看到无法确定 HTTPS 端口的警告，不影响 `http://localhost:5090` 的开发访问。需要验证 HTTPS 时使用项目的 `https` launch profile。
|
||||
检查响应中的 `database`、`redis.ready` 和 `rabbitMq.ready`。只配置了 Redis/RabbitMQ 连接串但服务未启动时，readiness 会按已配置依赖检查并返回 503。
|
||||
|
||||
### API 出现 HTTPS 重定向警告
|
||||
|
||||
仅使用 HTTP launch profile 时可能无法确定 HTTPS 端口，不影响 `http://localhost:5090` 的本地访问。需要验证 HTTPS 时使用项目的 `https` profile。
|
||||
|
||||
更多配置见[配置与后台任务](operations.md)，安全边界见[认证、授权与租户隔离](architecture/security-and-tenancy.md)。
|
||||
|
||||
Reference in New Issue
Block a user