OK

README.md

@@ -4,11 +4,152 @@
 
 ## 本地启动
 
-1. 复制 `.env.example` 为 `.env`，通过环境变量注入数据库配置（应用不会自动读取文件）。
-2. `cd web && pnpm install && pnpm build`
-3. `go run ./cmd/server`
+当前项目采用前后端分离运行：
 
-服务启动时执行幂等迁移并对 PostgreSQL、TDengine 进行带超时健康检查。生产环境应通过进程管理器注入环境变量，并仅在受信任内网暴露写入 API。
+- 后端：Go HTTP 服务，默认监听 `APP_PORT=8080`。
+- 前端：Vue 3 + Vite 开发服务，默认监听 `5173`。
+- 数据库：PostgreSQL 存储配置数据，TDengine 存储历史数据。
+
+注意：应用不会自动读取 `.env` 文件。启动后端前，必须先把 `.env` 中的配置注入当前 PowerShell 进程环境变量。
+
+### 1. 准备 `.env`
+
+复制 `.env.example` 为 `.env`，并填写实际数据库连接信息：
+
+```env
+APP_PORT=8080
+POSTGRES_HOST=数据库地址
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=实际密码
+POSTGRES_DATABASE=aquacontrolai
+POSTGRES_SSLMODE=disable
+TDENGINE_HOST=数据库地址
+TDENGINE_PORT=6041
+TDENGINE_USER=root
+TDENGINE_PASSWORD=实际密码
+TDENGINE_DATABASE=aquacontrolai
+HISTORY_RETENTION_DAYS=365
+COLLECTOR_WORKERS=8
+```
+
+如果数据库部署在云服务器上，需要确认本机可以访问云服务器的 PostgreSQL `5432` 和 TDengine REST `6041` 端口。
+
+### 2. 安装前端依赖
+
+首次启动前执行：
+
+```powershell
+Set-Location "E:\Vibe Coding\AquaControlAI\web"
+pnpm install
+```
+
+如遇到 `esbuild` 构建脚本审批问题，执行：
+
+```powershell
+Set-Location "E:\Vibe Coding\AquaControlAI"
+pnpm approve-builds --all
+```
+
+### 3. 启动后端
+
+打开一个 PowerShell 窗口，执行：
+
+```powershell
+Set-Location "E:\Vibe Coding\AquaControlAI"
+
+Get-Content .env -Encoding UTF8 | ForEach-Object {
+  $line = $_.Trim()
+  if ($line -and -not $line.StartsWith("#") -and $line -match "^([^=]+)=(.*)$") {
+    [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), "Process")
+  }
+}
+
+go run ./cmd/server
+```
+
+后端启动时会执行幂等迁移，并对 PostgreSQL、TDengine 进行带超时健康检查。如果数据库连接失败，后端会直接退出。
+
+### 4. 启动前端
+
+另打开一个 PowerShell 窗口，执行：
+
+```powershell
+Set-Location "E:\Vibe Coding\AquaControlAI\web"
+pnpm dev
+```
+
+浏览器访问：
+
+```text
+http://127.0.0.1:5173
+```
+
+Vite 已配置 `/api` 代理到 `http://127.0.0.1:8080`，所以前端页面会通过本地后端访问接口。
+
+### 5. 验证服务
+
+验证后端健康检查：
+
+```powershell
+Invoke-RestMethod "http://127.0.0.1:8080/api/v1/health"
+```
+
+验证前端代理到后端是否正常：
+
+```powershell
+Invoke-RestMethod "http://127.0.0.1:5173/api/v1/health"
+```
+
+正常返回应包含：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "status": "ok"
+  }
+}
+```
+
+## 停止服务
+
+如果后端和前端是在两个 PowerShell 窗口中直接启动的，分别在对应窗口按：
+
+```text
+Ctrl + C
+```
+
+如果服务在后台运行，或窗口已经关闭，可以按端口查找并停止进程。
+
+停止后端 `8080` 端口：
+
+```powershell
+$conn = Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue
+if ($conn) {
+  Stop-Process -Id $conn.OwningProcess -Force
+}
+```
+
+停止前端 `5173` 端口：
+
+```powershell
+$conn = Get-NetTCPConnection -LocalPort 5173 -ErrorAction SilentlyContinue
+if ($conn) {
+  Stop-Process -Id $conn.OwningProcess -Force
+}
+```
+
+确认端口已释放：
+
+```powershell
+Get-NetTCPConnection -LocalPort 8080,5173 -ErrorAction SilentlyContinue
+```
+
+没有输出表示端口已经释放。
+
+生产环境应通过进程管理器注入环境变量，并仅在受信任内网暴露写入 API。
 
 ## 安全说明