211 lines
7.6 KiB
Markdown
211 lines
7.6 KiB
Markdown
# 空数据库到租户建站
|
||
|
||
本页记录 Development 环境从全新 PostgreSQL 数据库完成平台管理员、租户、Owner 激活、网站发布和学生端访问的真实流程。数据库迁移只由 `Tiku.DbMigrator` 执行，API 不会自动更新 Schema。
|
||
|
||
## 1. 准备环境
|
||
|
||
需要 .NET 10、Node.js 24+、npm 11+、PostgreSQL、Redis，以及 `psql`、`createdb`、`dropdb`。
|
||
|
||
```bash
|
||
dotnet --version
|
||
node --version
|
||
npm --version
|
||
pg_isready -h 127.0.0.1 -p 5432
|
||
redis-cli -h 127.0.0.1 -p 6379 ping
|
||
```
|
||
|
||
首次拉取代码后安装依赖：
|
||
|
||
```bash
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
npm --prefix Tiku.PlatformAdmin.Web install
|
||
npm --prefix /path/to/tiku-saas-web install
|
||
```
|
||
|
||
## 2. 创建空数据库
|
||
|
||
以下操作只针对本地数据库 `tiku`。如果它已经包含需要保留的数据，请先备份，不要执行清理命令。
|
||
|
||
```bash
|
||
dropdb --if-exists -h 127.0.0.1 -U <数据库用户> tiku
|
||
createdb -h 127.0.0.1 -U <数据库用户> tiku
|
||
```
|
||
|
||
Development 未配置连接串时默认使用当前系统用户连接本机 `tiku`。其他用户或端口应显式设置：
|
||
|
||
```bash
|
||
export ConnectionStrings__Database='Host=127.0.0.1;Port=5432;Database=tiku;Username=<数据库用户>;Password=<本地密码>'
|
||
```
|
||
|
||
不要把连接串、密码或 Token 写入 `appsettings*.json`、README 或 Git。
|
||
|
||
## 3. 初始化目录、starter 套餐和首个平台账号
|
||
|
||
先设置一次性 Bootstrap 参数，再执行生产式空库初始化：
|
||
|
||
```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
|
||
```
|
||
|
||
该命令按固定顺序执行：
|
||
|
||
1. EF Core Migration；
|
||
2. Feature、Permission、菜单和额度目录；
|
||
3. 内置 `starter` 套餐及其已发布版本；
|
||
4. 可选的平台超级管理员 Bootstrap。
|
||
|
||
`starter` 是零元、CNY、已发布的建站基础套餐，包含 `core.backoffice` 和 `marketing.site_content`。首个平台账号使用临时密码，首次登录必须改密。
|
||
|
||
清除 Bootstrap 密码并再运行一次 Migrator，确认日常重复执行不会创建演示租户或重复目录：
|
||
|
||
```bash
|
||
unset TIKU_BOOTSTRAP_PLATFORM_ADMIN_PASSWORD
|
||
unset TIKU_BOOTSTRAP_PLATFORM_ADMIN_EMAIL
|
||
unset TIKU_BOOTSTRAP_PLATFORM_ADMIN_NAME
|
||
|
||
dotnet run --project Tiku.DbMigrator -- --skip-development-seed
|
||
```
|
||
|
||
Migration 需要 `citext`、`ltree` 和 `pg_trgm` 扩展。执行用户必须可以创建这些扩展，或由数据库管理员预先安装。
|
||
|
||
## 4. 启动真实服务
|
||
|
||
确保 Redis 已运行，然后从后端仓库启动 API：
|
||
|
||
```bash
|
||
export ASPNETCORE_ENVIRONMENT=Development
|
||
export ConnectionStrings__Redis='localhost:6379,abortConnect=false'
|
||
dotnet run --project Tiku.Api --launch-profile http
|
||
```
|
||
|
||
API 在 Development 会同时拉起平台管理端 Vite 服务：
|
||
|
||
- 平台管理端：<http://localhost:5173>
|
||
- API：<http://localhost:5090>
|
||
- Scalar：<http://localhost:5090/scalar/v1>
|
||
- OpenAPI：<http://localhost:5090/openapi/v1.json>
|
||
- Readiness：<http://localhost:5090/api/health/ready>
|
||
|
||
不要使用 `http://localhost:5090/platform-admin/` 作为开发入口；该路径受 API 授权保护，未登录访问返回 401。
|
||
|
||
在 `tiku-saas-web` 仓库另开终端，使用真实 API 模式启动租户前端：
|
||
|
||
```bash
|
||
VITE_DATA_MODE=api \
|
||
VITE_DEV_API_TARGET='http://localhost:5090' \
|
||
npm run dev -- --host 0.0.0.0 --port 5180
|
||
```
|
||
|
||
浏览器始终请求同源 `/api`，Vite 只在服务端把它代理到 `VITE_DEV_API_TARGET`。代理保留原始 Host，因此 `school.localhost` 能由后端解析到正确租户。
|
||
|
||
## 5. 浏览器建站流程
|
||
|
||
### 5.1 平台首次登录
|
||
|
||
1. 打开 <http://localhost:5173>；
|
||
2. 使用 Bootstrap 邮箱和临时密码登录；
|
||
3. 按页面要求设置新密码；
|
||
4. 进入“租户管理”。
|
||
|
||
### 5.2 创建租户和本地域名
|
||
|
||
点击“新建租户”，至少填写：
|
||
|
||
- 租户短编码，例如 `school`；
|
||
- 租户名称；
|
||
- 主域名 `school.localhost`；
|
||
- Owner 姓名；
|
||
- Owner 邮箱或手机号。
|
||
|
||
不选择套餐时，后端自动使用 `starter` 和默认试用天数。Development 配置只对精确的 `localhost` 或 `*.localhost` 启用 DNS/TLS 旁路，通常数秒内显示“DNS 与 TLS 已激活”。其他域名仍走真实 DNS 和网关流程。
|
||
|
||
### 5.3 签发并消费 Owner 链接
|
||
|
||
1. 域名 Active 后点击“领取激活链接”；
|
||
2. 填写审计原因并确认；
|
||
3. 立即保存弹窗中的一次性链接；
|
||
4. 用完整链接打开 `http://school.localhost:5180/activate/...#token=...`；
|
||
5. Owner 设置密码后自动进入 `/manage/onboarding`。
|
||
|
||
Token 只在签发成功弹窗显示一次。租户前端读入 Fragment 后立即清除地址栏；后端消费后不能重放。平台管理员看不到 Owner 密码，也不需要审批 Owner 激活。
|
||
|
||
### 5.4 配置并发布
|
||
|
||
向导依次完成：品牌信息、模板、主题样式、页面模块、桌面/移动预览、发布上线。保存草稿不会影响学生端；发布成功后 Runtime 读取已发布配置。
|
||
|
||
打开或刷新 <http://school.localhost:5180/>，应看到新的品牌、导航、主题和首页模块。退出租户后台后，可在 <http://school.localhost:5180/manage/login> 使用 Owner 账号重新登录。
|
||
|
||
## 6. 预期状态
|
||
|
||
| 阶段 | 预期状态 |
|
||
| --- | --- |
|
||
| 刚创建域名 | `pending` |
|
||
| Development 后台任务处理完成 | 域名 `active` |
|
||
| Owner 尚未领取链接 | `ready_to_issue` |
|
||
| 链接签发 | `issued` |
|
||
| Owner 激活并登录 | 进入 `/manage/onboarding` |
|
||
| 草稿完成但未发布 | `ready_to_launch` |
|
||
| 发布完成 | 学生端显示已发布配置 |
|
||
|
||
## 7. 常见问题
|
||
|
||
### `.localhost` 一直 Pending
|
||
|
||
确认 API 使用 `ASPNETCORE_ENVIRONMENT=Development`，并加载：
|
||
|
||
```json
|
||
{
|
||
"TenantDomains": {
|
||
"PollSeconds": 2,
|
||
"EnableDevelopmentLocalhostBypass": true
|
||
}
|
||
}
|
||
```
|
||
|
||
API 日志应出现 `Processed ... pending Development tenant domains`。非 Development 环境启用该旁路会在启动时失败。
|
||
|
||
### 激活页只出现 OPTIONS，没有 POST
|
||
|
||
不要把 API 地址配置为浏览器请求 Base URL。租户前端真实模式必须使用同源 `/api`，开发代理目标使用：
|
||
|
||
```bash
|
||
VITE_DEV_API_TARGET=http://localhost:5090
|
||
```
|
||
|
||
确保旧的 `VITE_API_BASE_URL` 未注入进程，并重启 Vite。
|
||
|
||
### 激活失败后地址栏已没有 Token
|
||
|
||
如果后端尚未消费 Token，可重新打开平台最初交付的完整链接。已经消费、过期或丢失明文时，必须由平台撤销并重新签发，不能从数据库或日志恢复。
|
||
|
||
### 发布后旧标签仍显示筹备页
|
||
|
||
草稿与已发布配置相互隔离。确认向导显示发布成功后，刷新学生端标签，让它重新请求 Runtime Bootstrap。
|
||
|
||
### Cookie 没有建立
|
||
|
||
必须通过 `school.localhost:5180` 访问激活和后台，不能改用 `localhost:5180` 或把 `tenantId` 填进请求。浏览器 Session 使用 Secure/HttpOnly Cookie，写请求使用 CSRF 双提交 Token，前端不得降级保存 JWT。
|
||
|
||
### Readiness 返回 503
|
||
|
||
确认 PostgreSQL 和 Redis 均可访问。匿名 readiness 只返回总体状态；依赖详情需要具有 `platform:operations:view` 权限的平台账号。
|
||
|
||
## 8. 清理
|
||
|
||
先停止 API、平台 Vite 和租户 Vite，再只删除明确的本地数据库：
|
||
|
||
```bash
|
||
dropdb -h 127.0.0.1 -U <数据库用户> tiku
|
||
```
|
||
|
||
该操作不可恢复，会删除本轮创建的平台账号、租户、Session、草稿和发布配置。
|
||
|
||
更多配置见[配置与后台任务](operations.md)，安全边界见[认证、授权与租户隔离](architecture/security-and-tenancy.md)。
|