Docker 部署
这是什么？
Zipoly Server 是一个打包好的程序，通过 Docker（一种虚拟容器技术）运行在你的服务器上。你不需要安装任何编程语言或依赖，只需要：
- 下载一个镜像包（
.tar，约 50 MB） - 用 Docker 加载并启动
- 打开浏览器就能用
没有 Docker？
- Windows：Docker Desktop（免费）
- Linux：
curl -fsSL https://get.docker.com | sh - Mac：Docker Desktop（免费）
安装后确认 docker --version 能输出版本号即可。
环境要求
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| 系统 | Linux / Windows / macOS | Ubuntu 22.04 LTS |
| 内存 | 2 GB | 4 GB+ |
| 磁盘 | 10 GB 可用空间 | SSD，预留处理文件的临时空间 |
| Docker | 20.10+ | 最新稳定版 |
第一步：获取镜像
从首页「团队版」按钮或 Gitee 发行版 下载 docker-dist.zip（约 50 MB），解压后得到发布目录 docker-dist/，内含 3 个文件：
| 文件 | 用途 |
|---|---|
zipoly-server-v2.1.0-image.tar | Docker 镜像包，docker load -i 直接加载 |
docker-compose.yml | 交付版编排文件（已配置好镜像，无需修改） |
DEPLOY.md | 本部署手册 |
# 加载镜像到本地 Docker（就像把压缩包解压到 Docker 里）
docker load -i zipoly-server-v2.1.0-image.tar
# 确认加载成功（应该能看到 zipoly-server:2.1.0）
docker images第二步：启动服务
推荐方式： 交付包已自带交付版 docker-compose.yml（已配置好镜像与数据卷），进入交付目录直接启动：
cd docker-dist
cp docker-compose.yml .. # 可选：放到你的项目目录
# 编辑 docker-compose.yml 替换 ZIPOLY__SERVER__API_KEY 后：
docker compose up -d也可以直接用 docker run 启动：
docker run -d \
--name zipoly-server \
--restart unless-stopped \
-p 8080:80 \
-v zipoly-data:/app/data \
-e ZIPOLY__SERVER__API_KEY=your-secure-api-key \
zipoly-server:2.1.0这些参数是什么意思？
| 参数 | 一句话解释 |
|---|---|
-d | 后台运行，不占用你的终端窗口 |
--name zipoly-server | 给容器起个名字，方便后续管理 |
--restart unless-stopped | 服务器重启后自动恢复服务 |
-p 8080:80 | 把容器的 80 端口映射到你电脑的 8080 端口 |
-v zipoly-data:/app/data | 创建一个持久化存储卷，数据不会因容器删除而丢失 |
-e ZIPOLY__SERVER__API_KEY=xxx | 设置 API 密钥（必填，换成你自己的密码） |
API Key 就像是服务的密码。调用接口时必须带上它，防止别人滥用你的服务。请把它换成复杂的随机字符串。
第三步：验证是否成功
# 命令行测试（把 your-secure-api-key 换成你刚才设置的密钥）
curl -H "X-API-Key: your-secure-api-key" http://localhost:8080/api/v1/health返回 {"status":"ok"} 就说明成功了。
然后打开浏览器访问 http://localhost:8080/，你应该能看到管理后台界面。
用 docker-compose 管理（推荐）
交付包自带的 docker-compose.yml 就是交付版（build: 段已替换为 image: 段，直接拉取本地镜像启动）。如果你要手写一份，参考以下模板：
services:
zipoly-server:
image: zipoly-server:2.1.0
container_name: zipoly-server
restart: unless-stopped
ports:
- "8080:80"
volumes:
- zipoly-data:/app/data
environment:
- ZIPOLY__SERVER__API_KEY=your-secure-api-key
- ZIPOLY__LOGGING__LEVEL=info
volumes:
zipoly-data:# 启动
docker compose up -d
# 查看日志（排查问题时用）
docker compose logs -f
# 停止
docker compose down配置域名和 HTTPS（生产环境必做）
如果你的服务器有公网 IP 或域名，建议加一层 nginx 反向代理 + SSL 证书：
server {
listen 443 ssl;
server_name zipoly.example.com; # 换成你的域名
ssl_certificate /etc/nginx/certs/zipoly.pem;
ssl_certificate_key /etc/nginx/certs/zipoly.key;
client_max_body_size 512m; # 允许上传大文件（重要！）
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 300s; # 大文件处理可能需要较长时间
}
}重要：上传大小限制
nginx 默认只允许上传 1MB 的文件，3D 模型通常远超这个大小。必须设置 client_max_body_size，否则上传会直接报 413 错误。
数据备份
所有数据（任务记录、上传文件、处理结果）都存在 /app/data 卷里。备份只需一行命令：
# 备份到当前目录
docker run --rm -v zipoly-data:/data -v $(pwd):/backup \
alpine tar czf /backup/zipoly-data-backup.tar.gz -C /data .
# 恢复（新环境）
docker run --rm -v zipoly-new-data:/data -v $(pwd):/backup \
alpine tar xzf /backup/zipoly-data-backup.tar.gz -C /data升级版本
# 1. 停止并删除旧容器（数据在卷中，不会丢）
docker stop zipoly-server && docker rm zipoly-server
# 2. 加载新版本镜像
docker load -i zipoly-server-v2.1.0-image.tar
# 3. 用交付包自带的编排文件重新启动（数据在卷中，不会丢）
cd docker-dist && docker compose up -d常见问题
启动后访问报 401？
请求时没有带 API Key，或者 Key 不对。检查 curl 命令里的 -H "X-API-Key: ..." 是否与启动时设置的一致。
大文件上传失败（413）？
前面提到的 nginx client_max_body_size 没设置，或者值太小。改成 512m 或更大。
端口 8080 被占用了？
换一个端口：-p 9090:80，然后访问 http://localhost:9090。
任务一直显示排队中？
服务器内存不够或并发数设得太低。见配置参考中的队列调优。
重启后数据没了？
启动时没挂载 -v zipoly-data:/app/data 卷。数据随容器删除而丢失，无法恢复。
更多接口层面的问题见 API 参考。