# shanxia2.0 Backend 生产部署说明

## 1. 上传到服务器

将 `backend/` 目录上传到：

```
/iflytek/shanxia2.0/backend
```

**必须排除**（否则 Linux 上会报 `bad interpreter: No such file or directory`）：

- `venv/`（**禁止上传本机 venv**，必须在服务器上用 `./start-prod.sh install` 重建）
- `logs/`、`__pycache__/`、`*.pyc`
- `graphify-out/`
- `uploads/`（若生产已有附件数据则保留服务器端目录）
- `.env`（开发配置，生产用 `.env.production`）

本地打包示例：

```bash
cd /path/to/shanxia2.0
tar czf shanxia2.0-backend.tar.gz \
  --exclude='backend/venv' \
  --exclude='backend/logs' \
  --exclude='backend/__pycache__' \
  --exclude='backend/graphify-out' \
  --exclude='backend/.env' \
  backend/
```

## 2. 服务器首次启动

```bash
cd /iflytek/shanxia2.0/backend
chmod +x start-prod.sh

# 首次：安装 Python 依赖（自动创建 venv）
./start-prod.sh install

# 启动（默认 127.0.0.1:9111，读取 .env.production）
./start-prod.sh start
```

## 3. 日常运维

```bash
./start-prod.sh status    # 查看状态
./start-prod.sh logs      # 最近日志
./start-prod.sh restart   # 发版后重启
./start-prod.sh stop      # 停止
```

健康检查：

```bash
curl -s http://127.0.0.1:9111/health
# {"status":"healthy"}
```

## 4. 配置文件

| 文件 | 用途 |
|---|---|
| `.env.production` | 生产环境变量（DB/Redis/MinIO/JWT/RSA 等） |
| `start-prod.sh` | 启动脚本（默认端口 **9111**） |

默认监听 `127.0.0.1:9111`，由 Nginx `:9911` 反代 `/api/*`，无需对公网开放 9111。

## 5. 与 Nginx 配合

Nginx 配置见仓库 `生产环境部署/nginx-shanxia2.0.conf`：

- 前端：`http://121.43.228.102:9911`
- API：`/api/` → `http://127.0.0.1:9111`

## 6. 常见问题

**Q: `bad interpreter: .../Users/.../venv/bin/python3: No such file or directory`**  
A: 误把本机 Mac 的 `venv/` 上传到了 Linux。在服务器执行：

```bash
cd /iflytek/shanxia2.0/backend
rm -rf venv
./start-prod.sh install
./start-prod.sh start
```

新版 `start-prod.sh` 也会自动检测并重建无效 venv。

**Q: 启动失败，日志报 ModuleNotFoundError**  
A: 执行 `./start-prod.sh install` 重新安装依赖。

**Q: 登录失败 / 公钥变化**  
A: 确认 `.env.production` 中 `LOGIN_RSA_PRIVATE_KEY_PEM` 已配置且未被修改。

**Q: 数据库连接失败**  
A: 检查服务器到 `47.99.164.66:3306` 网络与白名单。

**Q: 需要改端口**  
A: `PORT=9111 ./start-prod.sh restart` 或修改脚本默认值。