139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 本地开发快速开始
|
||
|
||
这份文档用于从全新开发环境启动 TIKU Backend、初始化 PostgreSQL，并完成平台管理员的首次登录。
|
||
|
||
## 1. 准备环境
|
||
|
||
需要安装：
|
||
|
||
- .NET 10 SDK；
|
||
- PostgreSQL（当前本地开发已验证 PostgreSQL 18）；
|
||
- `psql`、`createdb` 等 PostgreSQL 命令行工具。
|
||
|
||
确认工具可用：
|
||
|
||
```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 允许当前系统用户无密码登录，可以直接执行：
|
||
|
||
```bash
|
||
createdb -h 127.0.0.1 -U "$(whoami)" tiku
|
||
```
|
||
|
||
Development 环境未显式配置连接串时，API 和 DbMigrator 默认使用：
|
||
|
||
```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 或受控密钥存储。
|
||
|
||
## 4. 执行迁移并初始化管理员
|
||
|
||
```bash
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
|
||
```
|
||
|
||
DbMigrator 会执行全部 EF Core Migration，并在全新 Development 数据库中自动创建平台超级管理员：
|
||
|
||
```text
|
||
账号：admin@tiku.local
|
||
密码：首次初始化时安全随机生成，只在当前终端输出一次
|
||
```
|
||
|
||
请立即保存终端显示的临时密码。重复执行 DbMigrator 是幂等的，不会重复创建管理员、重置密码或再次显示密码。
|
||
|
||
管理员首次登录后必须：
|
||
|
||
1. 修改临时密码；
|
||
2. 绑定 TOTP MFA；
|
||
3. 保存一次性恢复码。
|
||
|
||
如果数据库已经包含平台管理员，自动初始化会跳过。不要为了重新获取密码删除包含业务数据的数据库。
|
||
|
||
## 5. 启动 API 和平台后台
|
||
|
||
```bash
|
||
dotnet run --project Tiku.Api
|
||
```
|
||
|
||
默认开发地址：
|
||
|
||
- 平台后台：<http://localhost:5090/platform-admin/>
|
||
- Scalar API 文档：<http://localhost:5090/scalar/v1>
|
||
- OpenAPI JSON：<http://localhost:5090/openapi/v1.json>
|
||
- 健康检查：<http://localhost:5090/api/health>
|
||
|
||
平台后台默认连接同源真实 API，不会回退到 Mock 数据。当前开放的是已有后端契约的概览、租户、员工、审计和告警等页面；尚未接入真实接口的模块暂不开放。
|
||
|
||
## 6. 可选：启动 Worker
|
||
|
||
需要调试后台任务时，另开终端并使用相同数据库连接：
|
||
|
||
```bash
|
||
dotnet run --project Tiku.Worker
|
||
```
|
||
|
||
普通 API 开发不要求同时启动 Worker。
|
||
|
||
## 7. 开发前验证
|
||
|
||
```bash
|
||
curl --fail http://localhost:5090/api/health
|
||
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
|
||
```
|
||
|
||
PostgreSQL 特有的 Migration、约束、事务和租户隔离行为必须使用真实 PostgreSQL 验证，不能只依赖 EF InMemory 测试。
|
||
|
||
## 常见问题
|
||
|
||
### 连接 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` 指向正确的主机、端口、数据库和用户。
|
||
|
||
### 首次迁移无法创建扩展
|
||
|
||
Migration 会创建 `citext` 和 `ltree` 扩展。初始化数据库的 PostgreSQL 用户必须有安装这些扩展所需的权限；请让本地数据库管理员预先安装扩展或授予对应权限。
|
||
|
||
### 没看到管理员临时密码
|
||
|
||
临时密码只在全新 Development 数据库首次创建管理员时显示。如果管理员绑定已经存在，迁移会安全跳过。请使用已有管理员账号的密码恢复流程，不要在源码或文档中添加固定密码。
|
||
|
||
### API 启动后出现 HTTPS 重定向警告
|
||
|
||
本地仅使用 HTTP profile 时可能看到无法确定 HTTPS 端口的警告，不影响 `http://localhost:5090` 的开发访问。需要验证 HTTPS 时使用项目的 `https` launch profile。
|