提交

README.md

@@ -14,13 +14,15 @@
 ```bash
 # 终端 1 —— 后端 API（http://localhost:8000）
 cd backend
-uv run uvicorn app.main:app --reload --port 8000
+env -u SSLKEYLOGFILE uv run uvicorn app.main:app --reload --port 8000
 
 # 终端 2 —— 前端开发服务器（http://localhost:5173）
 cd frontend
 pnpm dev
 ```
 
+> `env -u SSLKEYLOGFILE` 是本机（Windows）必需的：用户环境变量 `SSLKEYLOGFILE` 值开头混有不可见控制符，asyncpg 建连即崩。详见下文「快速开始（开发模式）」与「常见问题」。
+
 首次运行前先安装依赖：后端 `uv sync`（backend 下）、前端 `pnpm install`（frontend 下）。
 浏览器打开 http://localhost:5173 即可使用。详细说明见下文「快速开始（开发模式）」。
 
@@ -115,12 +117,25 @@ pip install uv
 
 ### 1) 后端
 
+实际启动命令（venv 解释器直启，日志重定向到仓库根 `backend_run.log`，改代码自动热重载）：
+
 ```bash
 cd backend
-uv sync                                    # 创建 .venv 并安装依赖（首次）
-uv run uvicorn app.main:app --reload --port 8000
+uv sync                                    # 创建 .venv 并安装依赖（仅首次）
+env -u SSLKEYLOGFILE .venv/Scripts/python.exe -m uvicorn app.main:app --reload --port 8000 > ../backend_run.log 2>&1
 ```
 
+看日志：`tail -f backend_run.log`；确认起没起：`curl http://localhost:8000/api/health`。
+
+等价的 `uv run` 写法（不带日志重定向，直接打到当前终端）：
+
+```bash
+cd backend
+env -u SSLKEYLOGFILE uv run uvicorn app.main:app --reload --port 8000
+```
+
+- **`env -u SSLKEYLOGFILE`（本机 Windows 必需）**：用户环境变量 `SSLKEYLOGFILE` 的值开头混有 U+202A 不可见控制符，asyncpg 建连时执行 `ssl.keylog_filename` 直接抛 `OSError: [Errno 22]`，uvicorn 启动即崩。Git Bash 下用 `env -u` 剔除即可；根治可 `setx SSLKEYLOGFILE "C:\Users\cirry\Desktop\fhzg.log"`（重开终端后不再需要前缀）。验证：`python -c "import os; print(repr(os.environ.get('SSLKEYLOGFILE')))"`。
+- **Windows `--reload` 僵死**：watcher 偶尔改文件不重载且日志无 Reloading 行，此时只能杀进程树重启——`netstat -ano | grep :8000` 找 PID，`taskkill //PID <pid> //T //F`。
 - 数据库结构由 Alembic 管理：首次部署/更新代码后先执行 `uv run alembic upgrade head`（见「初始化登录系统」）。
 - 交互式 API 文档：http://localhost:8000/docs
 
@@ -306,6 +321,8 @@ volumes: { pgdata: {} }
 - **真实标的首次回测慢/拉取失败**：首次需联网请求 Tushare（数秒）。Tushare 对 `adj_factor` 限频（每小时 1 次），触发时自动退化为不复权日线，不影响回测。数据已本地缓存，二次回测秒出。若 Tushare 积分不足，`uv add akshare` 后将自动用 AKShare 兜底。
 - **高价股（如茅台）回测 0 信号**：一手太贵买不起。默认初始资金已设为 100 万；如仍不够，在表单调高「初始资金」。
 - **Python 3.14 兼容**：MVP 依赖（fastapi/sqlalchemy/pandas/numpy）均已支持；指标用纯 Python 实现，不依赖 TA-Lib 的 C 库，Windows 免编译。
+- **后端启动即崩，栈在 asyncpg 深处（`OSError: [Errno 22] Invalid argument`）**：是本机环境变量 `SSLKEYLOGFILE` 值里混入的 U+202A 不可见控制符所致，不是数据库问题。Git Bash 下启动命令前加 `env -u SSLKEYLOGFILE`；或 `setx SSLKEYLOGFILE "C:\Users\cirry\Desktop\fhzg.log"` 重写该变量后重开终端。
+- **uvicorn `--reload` 改代码不生效**：Windows 下 watcher 会僵死（日志无 Reloading 行，touch 无效）。`netstat -ano | grep :8000` 找到 PID 后 `taskkill //PID <pid> //T //F` 杀进程树重启。
 
 ---