feat: 增加 YAML 配置与一键启动脚本

backend/README.md

@@ -32,17 +32,65 @@ backend/
     services/                # 跨模块应用服务
     workers/                 # 后台任务入口
   requirements.txt           # 后端第三方依赖
+  config.example.yaml        # 可提交的脱敏配置模板
+  config.yaml                # 本地配置，已忽略，环境变量可覆盖
   logs/                      # 本地开发日志目录，生产环境建议挂载到独立日志盘
 ```
 
+## 配置
+
+先复制本地配置并填写数据库凭据：
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+后端默认读取 `config.yaml`，配置优先级为：
+
+```text
+环境变量 > BACKEND_CONFIG_FILE 指定的 YAML > backend/config.yaml > 代码默认值
+```
+
+前后端端口、数据库地址、跨域来源、日志路径和计算状态轮询参数均可在 YAML 中
+配置。敏感信息或不同环境的差异建议通过环境变量覆盖，不要写入仓库。YAML 中的
+相对日志路径以该 YAML 文件所在目录为基准。使用其他配置文件时：
+
+```bash
+BACKEND_CONFIG_FILE=./config.prod.yaml uvicorn app.main:app --reload --port 17861
+```
+
+本机直连 PostgreSQL 时，数据库配置拆分为地址、用户名和密码：
+
+```yaml
+server:
+  frontend_port: 16801
+  backend_port: 17861
+
+database:
+  url: postgresql+psycopg://localhost:5432/yg_ft
+  username: yg_ft
+  password: "change_me"
+```
+
+服务启动时会安全拼装完整连接串；用户名或密码中的特殊字符会自动编码。Docker
+和生产环境仍可用完整的 `DATABASE_URL` 环境变量覆盖以上三项。
+
+这里的 `5432` 是宿主机 PostgreSQL 默认端口；如果数据库容器映射到 `15432`，
+将 YAML 中的端口改为 `15432` 即可。
+
+`server.frontend_port` 和 `server.backend_port` 由根目录的
+`scripts/start-dev.sh` 读取，并分别传给 Vite 和 Uvicorn。未配置
+`app.cors_allow_origins` 时，本机 CORS 来源会跟随前端端口。直接手工执行
+`uvicorn` 时仍需通过 `--port` 指定监听端口。
+
 ## 本地启动
 
 ```bash
 cd backend
-python -m venv .venv
-.venv\Scripts\activate
+/opt/miniconda3/bin/python3 -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt
-uvicorn app.main:app --reload
+uvicorn app.main:app --reload --port 17861
 ```
 
 健康检查：