update

README.md

@@ -68,14 +68,54 @@ YG_FT/
 
 > 说明：`audit`、`retention` 模块当前未拆为独立 REST 路由——审计接口挂在 `system` 下、留存策略嵌套于租户资源；用户「页面权限」精细控制 UI 仍为占位，待后续版本补齐。数据层当前为内存/本地存储实现，生产环境按 `docs/postgres-schema.sql` 迁移 PostgreSQL。
 
+## 首次环境准备（新人 / 新机器）
+
+> 后端与算力服务都运行在 **WSL2** 中（Windows 原生 Python / anaconda 依赖不兼容）。第一次拉代码、机器上没有任何环境时，按下面顺序一次性准备好；日常启动见下方「后端启动」「算力服务启动」。
+
+### 1. 基础运行时
+- **WSL2**：Windows 终端执行 `wsl --install`（默认 Ubuntu），重启生效。
+- **Python ≥ 3.9（推荐 3.12）**，在 WSL 内确认：
+  ```bash
+  python3 --version
+  ```
+  版本过低或未安装：`sudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip`。
+- **Node.js 18+**：前端在 **Windows 终端**安装并运行（不要放进 WSL，否则热更新跨 `/mnt` 文件系统很慢）。
+
+### 2. 数据库 PostgreSQL（首次需自建）
+后端默认连接 `postgresql+psycopg://yg_ft:change_me@localhost:15432/yg_ft`。首次没有数据库时，推荐用 Docker 一键起：
+```bash
+docker run -d --name yg_ft_pg -p 15432:5432 \
+  -e POSTGRES_USER=yg_ft -e POSTGRES_PASSWORD=change_me -e POSTGRES_DB=yg_ft \
+  postgres:16
+```
+无 Docker 时，可在 WSL 内 `sudo apt install -y postgresql` 后手动建库与用户。后端首次启动会自动建表并写入内置管理员账号（详见「后端启动」）。
+
+### 3. 后端 / 算力 venv 首次创建
+后端与算力各有独立 venv，首次需在 WSL 中创建并安装依赖（完整命令见下方启动小节）：
+- 后端：`cd /mnt/e/yg_ft/backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
+- 算力：`cd /mnt/e/yg_ft && source compute/.venv/bin/activate && pip install -r compute/requirements.txt`（compute 使用绝对导入 `compute.*`，须在仓库根目录操作）
+
+### 4. 前端首次安装
+在 Windows 终端：
+```powershell
+cd e:\yg_ft\frontend
+npm install
+npm run dev
+```
+
+---
+
 ## 后端启动
 
+> 后端需在 **WSL 终端** 中启动：Windows 的 anaconda 环境依赖不兼容，且项目 venv 为 Linux 版（使用 `bin/activate` 而非 `Scripts`）。若 `.wslconfig` 使用 `networkingMode=mirrored`，uvicorn 必须绑定 `--host 0.0.0.0` 才能被 Windows 侧 `localhost` 访问。
+
 ```bash
-cd backend
-python -m venv .venv
-.venv\Scripts\activate
+# 在 WSL 终端中执行
+cd /mnt/e/yg_ft/backend
+python3 -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt
-uvicorn app.main:app --reload --port 17861
+uvicorn app.main:app --host 0.0.0.0 --port 17861 --reload
 ```
 
 默认接口前缀为 `/modelTF`，例如：
@@ -118,14 +158,14 @@ npm run dev
 
 ## 算力服务启动
 
-算力服务位于 `compute/` 目录，拥有**独立虚拟环境（不复用后端 venv）**。
-代码使用绝对导入 `compute.*`，因此必须从**仓库根目录（`yg_ft/`）**启动，
-不能先 `cd compute` 再启动（否则报 `No module named 'compute'`）。
+> 算力服务同样需在 **WSL 终端** 中启动，且拥有**独立虚拟环境（不复用后端 venv）**。代码使用绝对导入 `compute.*`，因此必须从**仓库根目录（`/mnt/e/yg_ft`）**执行，不能先 `cd compute` 再启动（否则报 `No module named 'compute'`）。若 `.wslconfig` 使用 `networkingMode=mirrored`，uvicorn 需绑定 `--host 0.0.0.0` 才能被 Windows 侧 `localhost` 访问。
 
 ```bash
-# 在仓库根目录 yg_ft/ 下执行
-source compute/.venv/bin/activate                        # 激活独立 venv（Windows 用 compute\.venv\Scripts\activate）
-pip install -r compute/requirements.txt                  # 首次安装依赖
+# 在 WSL 终端中执行（必须位于仓库根目录 yg_ft/）
+cd /mnt/e/yg_ft
+python3 -m venv compute/.venv
+source compute/.venv/bin/activate
+pip install -r compute/requirements.txt
 uvicorn compute.api.main:app --host 0.0.0.0 --port 19100 --reload
 ```