191 lines
7.9 KiB
Markdown
191 lines
7.9 KiB
Markdown
# 本地开发快速上手
|
||
|
||
本页用于日常开发：初始化依赖、迁移数据库、启动 API/Worker/平台前端并完成基础验证。若要从空数据库验收“创建租户 → Owner 激活 → 发布站点”的完整流程，请改看[空数据库到租户建站验收](tenant-provisioning.md)。
|
||
|
||
## 前置依赖
|
||
|
||
- .NET 10 SDK
|
||
- Node.js 24+、npm 11+
|
||
- Docker Desktop（通过 Docker Compose 提供 PostgreSQL 18、Redis 7 和 MinIO）
|
||
|
||
```bash
|
||
dotnet --version
|
||
node --version
|
||
npm --version
|
||
docker info
|
||
docker compose version
|
||
```
|
||
|
||
首次拉取代码后恢复依赖：
|
||
|
||
```bash
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
npm --prefix Tiku.PlatformAdmin.Web install
|
||
```
|
||
|
||
## 启动 PostgreSQL、Redis 与对象存储
|
||
|
||
首次启动时，先在仓库根目录复制环境变量模板：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
`.env` 已被 Git 忽略。默认值与 `compose.yaml` 一致，可直接用于本机开发；如果修改数据库账号、密码或端口，必须同时修改 Compose 变量和 `ConnectionStrings__Database`/`ConnectionStrings__Redis`。不要把真实密码、Token 或生产连接串写入 `.env.example`。
|
||
|
||
Docker Compose 会自动读取根目录 `.env`。在启动 .NET 运行时的每个终端中，还必须先导入同一个文件：
|
||
|
||
```bash
|
||
set -a
|
||
source .env
|
||
set +a
|
||
```
|
||
|
||
如果跳过这一步，DbMigrator、API 和 Worker 就无法获得 Docker PostgreSQL/Redis 的连接配置。导入后再启动依赖并等待健康检查通过：
|
||
|
||
```bash
|
||
docker compose up -d --wait
|
||
docker compose ps
|
||
docker compose exec postgres pg_isready -U tiku -d tiku
|
||
docker compose exec redis redis-cli ping
|
||
curl --fail http://127.0.0.1:9000/minio/health/live
|
||
```
|
||
|
||
默认只监听本机回环地址：
|
||
|
||
```text
|
||
PostgreSQL: 127.0.0.1:5432，数据库 tiku，用户 tiku，密码 tiku_dev
|
||
Redis: 127.0.0.1:6379
|
||
MinIO API: 127.0.0.1:9000，Access Key tiku，Secret Key tiku_minio_dev
|
||
MinIO 控制台: http://127.0.0.1:9001
|
||
```
|
||
|
||
Development 配置会把 `local_dev` 对象存储指向该 MinIO；没有完整阿里云 OSS 凭据时也会自动回退到 `local_dev`。文件内容保存在 MinIO 数据卷，PostgreSQL 只保存业务元数据和对象引用。
|
||
|
||
这些默认凭据仅用于本机开发，不能用于共享或生产环境。需要自定义数据库、MinIO 凭据或宿主机端口时，应在首次创建数据卷前编辑本地 `.env`，并同步修改应用连接串或 `Storage:S3Compatible` 配置：
|
||
|
||
```bash
|
||
# .env
|
||
TIKU_POSTGRES_DB='<数据库名>'
|
||
TIKU_POSTGRES_USER='<数据库用户>'
|
||
TIKU_POSTGRES_PASSWORD='<本地密码>'
|
||
TIKU_POSTGRES_PORT='<宿主机端口>'
|
||
TIKU_REDIS_PORT='<宿主机端口>'
|
||
TIKU_MINIO_ROOT_USER='<Access Key>'
|
||
TIKU_MINIO_ROOT_PASSWORD='<Secret Key>'
|
||
TIKU_MINIO_API_PORT='<宿主机 API 端口>'
|
||
TIKU_MINIO_CONSOLE_PORT='<宿主机控制台端口>'
|
||
```
|
||
|
||
保存后重新导入并启动：
|
||
|
||
```bash
|
||
set -a
|
||
source .env
|
||
set +a
|
||
docker compose up -d --wait
|
||
```
|
||
|
||
PostgreSQL 初始化变量不会修改已有数据卷中的账号或数据库。不要把自定义连接串、密码、Token 或私钥写入仓库。
|
||
|
||
日常暂停使用 `docker compose stop`，恢复使用 `docker compose start`。`docker compose down` 会删除容器和网络但保留命名数据卷；`docker compose down -v` 会永久删除本地 PostgreSQL、Redis 与 MinIO 数据，只能在明确不需要数据时使用。
|
||
|
||
## 迁移与初始化
|
||
|
||
API 不执行 Migration。数据库结构、内置权限/菜单目录和 `starter` 套餐统一由 `Tiku.DbMigrator` 初始化：
|
||
|
||
```bash
|
||
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
|
||
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>
|
||
|
||
开发启动配置监听 `0.0.0.0:5090`。如需让同一内网的其他设备访问平台 API，先查询本机内网 IP，然后在本地 `.env` 中加入该 Host：
|
||
|
||
```bash
|
||
ipconfig getifaddr en0 # macOS 示例
|
||
|
||
# 将实际地址写入 .env；数组索引 0/1 仍保留 localhost 和 127.0.0.1
|
||
Tenancy__Resolution__PlatformHosts__2=192.168.1.100
|
||
```
|
||
|
||
修改 `.env` 后必须重启 API。访问地址为 `http://<内网 IP>:5090`；如果请求已经到达 API 但返回 `Tenant was not found`，通常是内网 IP 未加入 `PlatformHosts`。其他设备仍无法连接时，再检查 macOS 防火墙和 Wi-Fi 客户端隔离。内网 IP 由 DHCP 变更后也要同步更新 `.env`。
|
||
|
||
后台循环不在 API 内运行。需要处理域名、订阅、任务队列、授权缓存失效或商业账务时，另开终端启动 Worker：
|
||
|
||
```bash
|
||
dotnet run --project Tiku.Worker
|
||
```
|
||
|
||
API 与 Worker 必须使用前面设置的同一 PostgreSQL、Redis 和对象存储。Worker 是通用 Host，环境名使用 `.env` 中的 `DOTNET_ENVIRONMENT`；每个新终端都需要重新执行 `set -a; source .env; set +a`，或使用 direnv 等本机工具自动导入。
|
||
|
||
## 验证修改
|
||
|
||
```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 报数据库不可用
|
||
|
||
先运行 `docker compose ps`，确认 PostgreSQL 为 `healthy`，再用 `env | grep -E 'ConnectionStrings__Database|DATABASE_URL'` 确认当前终端已经导入 `.env`。如果 `5432` 端口已被本机 PostgreSQL 占用，应停止该服务或通过 `TIKU_POSTGRES_PORT` 改用其他宿主机端口，并同步修改数据库连接串；非 Development 环境没有本地默认连接串。
|
||
|
||
### 找不到平台管理员临时密码
|
||
|
||
默认 Development seed 和显式 Bootstrap 都只在创建账号时输出一次临时密码，后续运行不会重放。不要从日志或数据库恢复明文；应通过受控流程重置，或在确认无需保留本地数据后重建开发数据库。
|
||
|
||
### Readiness 返回 503
|
||
|
||
`/api/system/health/ready` 会检查 PostgreSQL 和已配置的 Redis。先验证数据库连接；配置 Redis 后还需确认 Redis 可访问。匿名响应不会暴露依赖详情。
|
||
|
||
### 上传或导出提示对象存储不可用
|
||
|
||
运行 `docker compose ps` 并确认 MinIO 为 `healthy`，再检查 `http://127.0.0.1:9000/minio/health/live`。自定义 MinIO 凭据或端口后，必须同步设置 `Storage:S3Compatible` 或 `S3_ENDPOINT`、`S3_ACCESS_KEY`、`S3_SECRET_KEY` 与 `S3_SECURE`。
|
||
|
||
### API 启动了但后台任务不执行
|
||
|
||
Production 和常规 Development 都需要独立运行 `Tiku.Worker`。Development 仅额外在 API 中注册本地域名生命周期旁路，不代表 API 承载全部 Worker 循环。
|