Search-Goods/.trae/documents/在 Ubuntu 22.04（宝塔面板）部署商品查询系统的方案.md

总览

• 目标：在 Ubuntu 22.04（装有宝塔面板）部署现有 FastAPI + SQLite 项目，绑定域名并启用 HTTPS，支持前端查询与 Excel 导入。
• 推荐路径：使用宝塔 Nginx 站点做反向代理，后端用虚拟环境 + uvicorn 常驻（systemd）或使用宝塔的 Python 项目插件；也可选 Docker 方案。

路径A：Python 虚拟环境 + systemd + Nginx 反代（稳定通用）

1. 上传项目到服务器

• 位置：/www/wwwroot/product-query（宝塔默认网站目录）
• 结构：包含 app/、static/、requirements.txt、scripts/、README.md

2. 安装依赖并准备运行目录

• sudo apt update && sudo apt install -y python3.10-venv（22.04 默认 Python3.10）
• cd /www/wwwroot/product-query
• python3 -m venv venv && source venv/bin/activate
• pip install -r requirements.txt
• mkdir -p data && chown -R www:www /www/wwwroot/product-query

3. 创建 systemd 服务

• 新建 /etc/systemd/system/product-query.service：

[Unit]
Description=Product Query FastAPI
After=network.target

[Service]
WorkingDirectory=/www/wwwroot/product-query
ExecStart=/www/wwwroot/product-query/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 9000
Restart=always
User=www
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

• 执行：sudo systemctl daemon-reload && sudo systemctl enable product-query && sudo systemctl start product-query && sudo systemctl status product-query

4. 宝塔创建网站并配置反向代理

• 在宝塔面板 → 网站 → 添加站点，绑定你的域名（示例 query.example.com）
• 在该站点的“反向代理”中设置：
  • 目标地址：http://127.0.0.1:9000
  • 开启“缓存/压力测试”时先关闭，调试稳定后再按需开启
• SSL：在站点的“SSL”中申请 Let’s Encrypt 并开启强制 HTTPS

5. 验证

• curl http://127.0.0.1:9000/health 返回 {"status":"ok"}
• 访问 https://query.example.com/ 打开前端页面

路径B：宝塔 Python 项目插件（图形化管理）

1. 在宝塔应用商店安装“Python 项目管理器”（版本需支持 FastAPI/uvicorn）
2. 新建项目：

• 运行目录：/www/wwwroot/product-query
• 选择 Python 解释器或创建虚拟环境
• 安装依赖：在插件里执行 pip install -r requirements.txt
• 启动命令：uvicorn app.main:app --host 127.0.0.1 --port 9000
• 日志路径与守护设置按需配置

3. 按路径A第4步在 Nginx 站点做反向代理与 SSL

路径C：Docker / Compose（面板或命令行皆可）

1. 安装 Docker 与 Compose（或使用宝塔 Docker 管理器）

• sudo apt install -y docker.io docker-compose

2. 在项目目录执行：

• docker compose up -d（使用仓库内 docker-compose.yml）
• 容器监听 8000，宿主机映射 8000:8000，数据持久化到宿主 ./data

3. 在宝塔 Nginx 站点反代到 127.0.0.1:8000 并配置 SSL

数据与权限

• 数据库存放在 data/products.db，务必保留该目录的持久化
• 权限建议：chown -R www:www /www/wwwroot/product-query，确保 Nginx/反代用户读写正常（写入仅限后端进程）

运维与排错

• 服务日志：
  • systemd：journalctl -u product-query -f
  • Python插件/Docker：在面板或 docker logs -f product-query
• 常见问题：
  • 反代 502：检查后端是否启动、端口是否匹配、站点安全组/防火墙是否放行
  • 中文编码：浏览器显示正常；命令行可能乱码，不影响功能

上线Checklist

• 站点域名与反向代理已配置
• SSL 已启用且强制跳转 HTTPS
• 后端进程已常驻（systemd 或插件守护）
• /import 上传上限：在 Nginx/站点上传限制按需提高（如 50MB）
• 防火墙安全：只开放 80/443，后端端口用 127.0.0.1 回环

你需准备的信息

• 目标域名（如需绑定）
• 选择的部署路径（A/B/C），我可以据此输出一键命令与面板操作截图式步骤