# 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`：
  ```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（容器镜像服务）：
  ```bash
  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
  ```
  - 服务器直接拉取镜像并运行，跳过远端构建：
  ```bash
  docker pull ccr.ccs.tencentyun.com/<namespace>/<repo>:v1
  docker compose up -d
  ```


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