From 1aa1ed4829e617c228b10be823e3d5f136e5c5e3 Mon Sep 17 00:00:00 2001 From: xiong Date: Tue, 4 Aug 2026 17:46:01 +0800 Subject: [PATCH] chore(dev): simplify local Docker startup --- .env.example | 19 +++++++ .gitignore | 4 ++ README.md | 25 ++++++--- Tiku.Api/Properties/launchSettings.json | 4 +- docs/quickstart.md | 75 +++++++++++++++++-------- 5 files changed, 94 insertions(+), 33 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..1e9e2d3 --- /dev/null +++ b/.env.example @@ -0,0 +1,19 @@ +# Copy this file to .env before starting local infrastructure or .NET runtimes. +# These credentials match compose.yaml defaults and are for local development only. +TIKU_POSTGRES_DB=tiku +TIKU_POSTGRES_USER=tiku +TIKU_POSTGRES_PASSWORD=tiku_dev +TIKU_POSTGRES_PORT=5432 +TIKU_REDIS_PORT=6379 + +ASPNETCORE_ENVIRONMENT=Development +DOTNET_ENVIRONMENT=Development +ConnectionStrings__Database="Host=127.0.0.1;Port=5432;Database=tiku;Username=tiku;Password=tiku_dev" +ConnectionStrings__Redis="127.0.0.1:6379,abortConnect=false" + +Tenancy__Resolution__PlatformHosts__0=localhost +Tenancy__Resolution__PlatformHosts__1=127.0.0.1 + +# To access the platform API from another device on the LAN, uncomment this +# setting and replace the address with this development machine's current LAN IP. +# Tenancy__Resolution__PlatformHosts__2=192.168.1.100 diff --git a/.gitignore b/.gitignore index c575eb0..aa23432 100644 --- a/.gitignore +++ b/.gitignore @@ -374,3 +374,7 @@ FodyWeavers.xsd *.db-wal .idea/ + +# Local runtime configuration. Keep the documented template tracked. +.env +!.env.example diff --git a/README.md b/README.md index 6dee71b..aaed7e7 100644 --- a/README.md +++ b/README.md @@ -35,20 +35,29 @@ Tiku.IntegrationTests API、授权、EF 模型、迁移和真实 PostgreSQL 测 需要 .NET 10 SDK、Node.js 24+ 和 Docker Desktop。本地 PostgreSQL、Redis 与 S3 兼容对象存储统一由根目录的 `compose.yaml` 提供： ```bash -docker compose up -d --wait +cp .env.example .env +set -a +source .env +set +a -export ConnectionStrings__Database='Host=127.0.0.1;Port=5432;Database=tiku;Username=tiku;Password=tiku_dev' -export ConnectionStrings__Redis='127.0.0.1:6379,abortConnect=false' +docker compose up -d --wait dotnet restore TIKU-BACKEND.slnx dotnet build TIKU-BACKEND.slnx --no-restore -ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator -ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Api --launch-profile http -# 另开终端并设置相同连接串后启动 Worker -DOTNET_ENVIRONMENT=Development dotnet run --project Tiku.Worker +dotnet run --project Tiku.DbMigrator +dotnet run --project Tiku.Api --launch-profile http ``` -`docker compose ps` 应显示 PostgreSQL、Redis 与 MinIO 均为 `healthy`。Development 未配置阿里云 OSS 时，`local_dev` Provider 会把对象实际保存到 MinIO，而不是返回占位结果。默认账号和密码只用于本机开发，不能用于共享或生产环境。完整配置、停止和排障步骤见[本地开发快速上手](docs/quickstart.md)。 +另开终端启动 Worker 时必须再次导入 `.env`： + +```bash +set -a +source .env +set +a +dotnet run --project Tiku.Worker +``` + +必须先从 `.env.example` 创建本地 `.env`，并在每个运行 .NET 的新终端中导入；否则 DbMigrator、API 和 Worker 可能连接到错误的 PostgreSQL/Redis。`.env` 不进入 Git。`docker compose ps` 应显示 PostgreSQL、Redis 与 MinIO 均为 `healthy`。Development 未配置阿里云 OSS 时，`local_dev` Provider 会把对象实际保存到 MinIO，而不是返回占位结果。默认账号和密码只用于本机开发，不能用于共享或生产环境。完整配置、内网访问、停止和排障步骤见[本地开发快速上手](docs/quickstart.md)。 默认 Development seed 会在尚无平台角色绑定时创建平台管理员 `admin@tiku.local` 和演示数据；随机临时密码只在首次创建时输出。日常步骤见[本地开发快速上手](docs/quickstart.md)，不含演示数据的完整 SaaS 验收见[空数据库到租户建站验收](docs/tenant-provisioning.md)。 diff --git a/Tiku.Api/Properties/launchSettings.json b/Tiku.Api/Properties/launchSettings.json index fd6b4bd..51f5b1e 100644 --- a/Tiku.Api/Properties/launchSettings.json +++ b/Tiku.Api/Properties/launchSettings.json @@ -5,7 +5,7 @@ "commandName": "Project", "dotnetRunMessages": true, "launchBrowser": false, - "applicationUrl": "http://localhost:5090", + "applicationUrl": "http://0.0.0.0:5090", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development", "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy" @@ -15,7 +15,7 @@ "commandName": "Project", "dotnetRunMessages": true, "launchBrowser": false, - "applicationUrl": "https://localhost:7093;http://localhost:5090", + "applicationUrl": "https://localhost:7093;http://0.0.0.0:5090", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development", "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy" diff --git a/docs/quickstart.md b/docs/quickstart.md index 7c7c05a..02b057b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -25,7 +25,23 @@ 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 @@ -44,27 +60,29 @@ MinIO API: 127.0.0.1:9000，Access Key tiku，Secret Key tiku_minio_dev MinIO 控制台: http://127.0.0.1:9001 ``` -为 DbMigrator、API 和 Worker 设置相同的连接串： - -```bash -export ConnectionStrings__Database='Host=127.0.0.1;Port=5432;Database=tiku;Username=tiku;Password=tiku_dev' -export ConnectionStrings__Redis='127.0.0.1:6379,abortConnect=false' -``` - Development 配置会把 `local_dev` 对象存储指向该 MinIO；没有完整阿里云 OSS 凭据时也会自动回退到 `local_dev`。文件内容保存在 MinIO 数据卷，PostgreSQL 只保存业务元数据和对象引用。 -这些默认凭据仅用于本机开发，不能用于共享或生产环境。需要自定义数据库、MinIO 凭据或宿主机端口时，应在首次创建数据卷前设置 Compose 变量，并同步修改应用连接串或 `Storage:S3Compatible` 配置： +这些默认凭据仅用于本机开发，不能用于共享或生产环境。需要自定义数据库、MinIO 凭据或宿主机端口时，应在首次创建数据卷前编辑本地 `.env`，并同步修改应用连接串或 `Storage:S3Compatible` 配置： ```bash -export TIKU_POSTGRES_DB='<数据库名>' -export TIKU_POSTGRES_USER='<数据库用户>' -export TIKU_POSTGRES_PASSWORD='<本地密码>' -export TIKU_POSTGRES_PORT='<宿主机端口>' -export TIKU_REDIS_PORT='<宿主机端口>' -export TIKU_MINIO_ROOT_USER='' -export TIKU_MINIO_ROOT_PASSWORD='' -export TIKU_MINIO_API_PORT='<宿主机 API 端口>' -export TIKU_MINIO_CONSOLE_PORT='<宿主机控制台端口>' +# .env +TIKU_POSTGRES_DB='<数据库名>' +TIKU_POSTGRES_USER='<数据库用户>' +TIKU_POSTGRES_PASSWORD='<本地密码>' +TIKU_POSTGRES_PORT='<宿主机端口>' +TIKU_REDIS_PORT='<宿主机端口>' +TIKU_MINIO_ROOT_USER='' +TIKU_MINIO_ROOT_PASSWORD='' +TIKU_MINIO_API_PORT='<宿主机 API 端口>' +TIKU_MINIO_CONSOLE_PORT='<宿主机控制台端口>' +``` + +保存后重新导入并启动： + +```bash +set -a +source .env +set +a docker compose up -d --wait ``` @@ -77,7 +95,7 @@ PostgreSQL 初始化变量不会修改已有数据卷中的账号或数据库。 API 不执行 Migration。数据库结构、内置权限/菜单目录和 `starter` 套餐统一由 `Tiku.DbMigrator` 初始化： ```bash -ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator +dotnet run --project Tiku.DbMigrator ``` 默认 Development seed 会在尚无平台角色绑定时创建 `admin@tiku.local`、演示租户和演示运营数据；随机临时密码只在首次创建时输出，首次登录必须改密。 @@ -102,7 +120,7 @@ dotnet run --project Tiku.DbMigrator -- \ 启动 API： ```bash -ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Api --launch-profile http +dotnet run --project Tiku.Api --launch-profile http ``` `Tiku.Api.csproj` 的 SPA Proxy 会在 Development 启动 `Tiku.PlatformAdmin.Web` 的 Vite 服务。默认入口： @@ -114,13 +132,24 @@ ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Api --launch-profil - Liveness： - Readiness： +开发启动配置监听 `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_ENVIRONMENT=Development dotnet run --project Tiku.Worker +dotnet run --project Tiku.Worker ``` -API 与 Worker 必须使用前面设置的同一 PostgreSQL、Redis 和对象存储。Worker 是通用 Host，环境名使用 `DOTNET_ENVIRONMENT`；每个新终端都需要重新设置连接串，或通过本机未跟踪的安全配置注入。 +API 与 Worker 必须使用前面设置的同一 PostgreSQL、Redis 和对象存储。Worker 是通用 Host，环境名使用 `.env` 中的 `DOTNET_ENVIRONMENT`；每个新终端都需要重新执行 `set -a; source .env; set +a`，或使用 direnv 等本机工具自动导入。 ## 验证修改 @@ -142,7 +171,7 @@ PostgreSQL 特有的 Migration、事务、约束和租户隔离行为必须由 ### API 报数据库不可用 -先运行 `docker compose ps`，确认 PostgreSQL 为 `healthy`，再核对 `ConnectionStrings__Database` 或 `DATABASE_URL`。如果 `5432` 端口已被本机 PostgreSQL 占用，应停止该服务或通过 `TIKU_POSTGRES_PORT` 改用其他宿主机端口；非 Development 环境没有本地默认连接串。 +先运行 `docker compose ps`，确认 PostgreSQL 为 `healthy`，再用 `env | grep -E 'ConnectionStrings__Database|DATABASE_URL'` 确认当前终端已经导入 `.env`。如果 `5432` 端口已被本机 PostgreSQL 占用，应停止该服务或通过 `TIKU_POSTGRES_PORT` 改用其他宿主机端口，并同步修改数据库连接串；非 Development 环境没有本地默认连接串。 ### 找不到平台管理员临时密码