Search-Goods/部署文档.md

Docker 部署指南

环境准备

• Ubuntu 22.04（或你的服务器环境）
• 已安装 Docker 与 Docker Compose（或宝塔 Docker 管理器）
• 域名与宝塔 Nginx（可选，用于反向代理与 SSL）

端口与目录

• 服务端口：57777（容器与宿主机均使用 57777）
• 数据持久化：./data:/app/data（SQLite 数据库）
• 静态资源挂载：./static:/app/static:ro（前端文件可直接热更新）

项目结构

• Dockerfile：镜像构建
• docker-compose.yml：编排与端口/挂载
• app/：后端 FastAPI
• static/：前端资源
• data/：数据库（运行时生成）

Gitea 流程（示例）

1. 在 Gitea 创建仓库，推送本项目代码
2. 服务器拉取：
   • git clone https://your-gitea/owner/repo.git /opt/product-query
   • cd /opt/product-query
3. 启动：
   • docker compose up --build -d
4. 验证：
   • curl http://127.0.0.1:57777/health 返回 {"status":"ok"}
   • 浏览器打开 http://SERVER_IP:57777/

宝塔面板（可选）

• 网站 → 添加站点 → 绑定域名
• 反向代理：目标 http://127.0.0.1:57777
• SSL：申请 Let’s Encrypt 并开启强制 HTTPS

更新前端与后端

• 前端：修改 static/ 文件后，容器会直接读取（因挂载为只读给容器）
• 后端：修改 app/ 或依赖后：
  • docker compose up --build -d
• 如构建缓存异常：
  • docker compose build --no-cache && docker compose up -d

数据与备份

• 数据库文件位于宿主机 ./data/products.db
• 建议每日备份该文件；导出可直接复制或后续加 /export 接口

常见问题

• 502 或无法访问：确认容器已启动且端口映射为 57777:57777
• 中文显示乱码：仅限命令行输出，页面显示正常；确保浏览器编码为 UTF-8

一键命令汇总

• 首次部署：

cd /opt/product-query
docker compose up --build -d

• 更新部署：

git pull
docker compose up --build -d

安全建议

• 宿主仅开放 80/443；57777 可通过回环访问并由 Nginx 反代对外
• 上传导入大小可在 Nginx/面板调整；建议限制文件类型为 Excel（.xlsx/.xls）

国内部署加速（腾讯云）

• Docker Hub 拉取加速：
  • 编辑 /etc/docker/daemon.json：

  {
    "registry-mirrors": [
      "https://mirror.ccs.tencentyun.com",
      "https://hub-mirror.c.163.com",
      "https://docker.mirrors.ustc.edu.cn"
    ]
  }
  

  • 重启 Docker：systemctl restart docker
• Python 依赖加速：镜像内已默认配置 pip 使用腾讯云源 https://mirrors.cloud.tencent.com/pypi/simple
• 预构建镜像：
  • 在本地构建并推送到腾讯云 TCR（容器镜像服务）：

  docker build -t ccr.ccs.tencentyun.com/<namespace>/<repo>:v1 .
  docker login ccr.ccs.tencentyun.com
  docker push ccr.ccs.tencentyun.com/<namespace>/<repo>:v1
  

  • 服务器直接拉取镜像并运行，跳过远端构建：

  docker pull ccr.ccs.tencentyun.com/<namespace>/<repo>:v1
  docker compose up -d
  

---

如需将 Compose 改为读取 .env（例如 PORT、令牌等），我可以补充 .env.example 与 docker-compose.yml 的 env_file 配置。当前方案保持简洁，端口固定为 57777。