# 宝塔面板 - 添加 Python 项目 填写说明

按截图「添加Python项目」表单，逐项填写如下。

## 前置条件

1. **Python 环境必须先修好**（环境管理里选 3.10 或 3.11）
   - SSH 验证：`python3.11 -c "import ssl; print(ssl.OPENSSL_VERSION)"`
   - 若报 `No module named '_ssl'`，先在服务器执行：
     ```bash
     yum install -y openssl openssl-devel
     AUTO_BUILD_PYTHON=1 bash /www/wwwroot/douyin/install.sh
     ```
   - 然后在宝塔 **环境管理** 添加解释器：`/usr/local/python3.11/bin/python3.11`

2. **安装 Node.js 18+**（软件商店 -> Node 版本管理器）

3. 将项目代码放到 `/www/wwwroot/douyin/`

---

## 使用宝塔安装的 Python（推荐）

若已在 **Python项目管理器 → 环境管理** 安装了 Python 3.11，一键配置：

```bash
cd /www/wwwroot/douyin
chmod +x backend/baota_use_panel_python.sh
bash backend/baota_use_panel_python.sh
```

脚本会自动扫描 `/home/www/server/pyporject_evn/versions/` 等宝塔目录，选用 **3.10+ 且带 SSL** 的版本，安装依赖、venv、Chromium。

若提示 **无 SSL**，先在 SSH 执行 `yum install -y openssl openssl-devel`，再在宝塔 **卸载并重装** Python 3.11。

---

## 表单填写

| 字段 | 填写值 | 说明 |
|------|--------|------|
| **项目名称** | `douyin` | 任意英文名 |
| **Python环境** | `3.11.x`（环境管理里带 SSL 的版本） | 不要选缺 _ssl 的坏环境 |
| **启动方式** | **命令行启动** | FastAPI 用 uvicorn，勿选 gunicorn/uwsgi |
| **项目路径** | `/www/wwwroot/douyin/backend` | **必须是 backend 目录**，不是项目根目录 |
| **启动命令** | `bash /www/wwwroot/douyin/backend/baota_start.sh` | 使用项目自带启动脚本 |
| **环境变量** | **从文件加载** | 文件路径：`/www/wwwroot/douyin/.env` |
| **启动用户** | `www` | 默认即可 |
| **安装依赖包** | `/www/wwwroot/douyin/backend/requirements.txt` | 宝塔自动 pip install |
| **项目初始化命令** | `bash /www/wwwroot/douyin/backend/baota_init.sh` | 装 Playwright、npm、构建前端 |

---

## .env 文件（项目根目录）

复制 `.env.example` 为 `/www/wwwroot/douyin/.env`：

```bash
cp /www/wwwroot/douyin/.env.example /www/wwwroot/douyin/.env
```

至少修改：

```
KEFU_SECRET_KEY=随机长字符串
KEFU_ADMIN_PASSWORD=强密码
KEFU_SERVE_WEB=true
PLAYWRIGHT_BROWSERS_PATH=/www/wwwroot/douyin/playwright-browsers
```

---

## 权限

```bash
chown -R www:www /www/wwwroot/douyin
chmod +x /www/wwwroot/douyin/backend/baota_init.sh
chmod +x /www/wwwroot/douyin/backend/baota_start.sh
chmod +x /www/wwwroot/douyin/backend/baota_fix.sh
chmod +x /www/wwwroot/douyin/install.sh
chmod +x /www/wwwroot/douyin/start.sh
```

## 报错快速修复

若浏览器访问 `http://IP:8000` 显示 **连接被拒绝 (ERR_CONNECTION_REFUSED)**：

```bash
bash /www/wwwroot/douyin/backend/baota_status.sh   # 诊断
bash /www/wwwroot/douyin/backend/baota_fix.sh      # 修依赖
bash /www/wwwroot/douyin/backend/baota_init.sh     # 初始化
```

然后在宝塔 **Python项目 -> douyin -> 设置** 里确认启动命令：

```bash
bash /www/wwwroot/douyin/backend/baota_start.sh
```

保存后点 **重启**。SSH 可手动测试：

```bash
bash /www/wwwroot/douyin/backend/baota_start.sh
# 另开终端: curl http://127.0.0.1:8000/api/health
```

**云服务器**还需在安全组放行 **TCP 8000**。

若日志出现 `.venv/bin/uvicorn 没有那个文件` 或 `No module named uvicorn`：

```bash
bash /www/wwwroot/douyin/backend/baota_fix.sh
```

然后在宝塔 **Python项目 -> douyin -> 设置** 里，把启动命令改成：

```bash
bash /www/wwwroot/douyin/backend/baota_start.sh
```

**切勿**在 Linux 上运行 `start_web.bat`。

---

## 常见错误

| 现象 | 原因 | 处理 |
|------|------|------|
| pip 报 SSL module not available | 宝塔 Python 环境缺 OpenSSL | 环境管理换 `/usr/local/python3.11/bin/python3.11` |
| fastapi 版本找不到 | 用了 Python 3.6 | 环境管理选 3.10+ |
| 启动后只有 API 无页面 | 未构建前端 | 重新运行 `baota_init.sh` |
| 权限不够 | 运行用户与属主不一致 | `chown -R www:www` |
| `.venv/bin/uvicorn` 不存在 | 宝塔默认启动命令错误 | 改为 `bash .../baota_start.sh` |
| `start_web.bat` 报错 | Windows 脚本不能在 Linux 运行 | 用 `bash start.sh` 或 `baota_start.sh` |
| `No module named uvicorn` | 依赖未装进当前 Python | 运行 `bash backend/baota_fix.sh` |
| Playwright chrome 不存在 | 未下载 Chromium | `bash backend/baota_playwright.sh` |

---

## 访问

- 管理后台：`http://服务器IP:8000`
- 健康检查：`http://服务器IP:8000/api/health`
- 默认账号：`admin` / `admin123`（首次启动后请修改）

## 反向代理（可选）

若要用域名 + HTTPS，在宝塔添加网站后，反向代理到 `http://127.0.0.1:8000`，参考 `deploy/nginx.conf.example`。