195 lines
6.8 KiB
Markdown
195 lines
6.8 KiB
Markdown
# 生产部署（Docker / 腾讯云 CVM）
|
||
|
||
单机 Docker Compose 方案：`Nginx + API + PostgreSQL + MinIO`，适合腾讯云轻量/ CVM。
|
||
|
||
## 架构
|
||
|
||
```
|
||
Internet ──:80/443──▶ 边缘网关（Caddy 推荐 / 或 CLB）
|
||
│
|
||
▼
|
||
web(nginx) :HTTP_PORT（默认 18080 → 容器 80）
|
||
├── / 前端 SPA
|
||
├── /api/* → api:8080（含 WebSocket）
|
||
├── /health → api
|
||
└── /files/* → minio:9000/kefu（图片公共读）
|
||
```
|
||
|
||
**两层分工（不要混为一谈）：**
|
||
|
||
| 层级 | 组件 | 职责 |
|
||
|------|------|------|
|
||
| 边缘 | 宿主机 Caddy（或 CLB） | 占 80/443、多域名、自动 HTTPS |
|
||
| 应用内 | compose 里的 `web`（Nginx） | SPA + `/api` + `/files` 路径反代 |
|
||
|
||
若机器上已有 `caddy` 占用 80/443（例如旧站 `kefu_sys`），**不要**让本项目 `HTTP_PORT=80`，应改用 `18080` 并由 Caddy 反代。
|
||
|
||
## 服务器准备（腾讯云）
|
||
|
||
1. 购买 **CVM / 轻量应用服务器**（建议 2 核 4G 起，系统 Ubuntu 22.04）
|
||
2. **安全组**放行：`22`、`80`（有证书再放 `443`）。应用内端口（如 `18080`）**不必**对公网开放
|
||
3. 安装 Docker：
|
||
|
||
```bash
|
||
# Ubuntu 示例
|
||
curl -fsSL https://get.docker.com | sh
|
||
sudo usermod -aG docker "$USER"
|
||
# 重新登录后 docker 无需 sudo
|
||
docker compose version
|
||
```
|
||
|
||
4. 上传代码到服务器，例如：
|
||
|
||
```bash
|
||
git clone <你的仓库地址> kefu_cloud
|
||
cd kefu_cloud
|
||
```
|
||
|
||
5. 部署前检查端口占用：
|
||
|
||
```bash
|
||
sudo ss -tlnp | grep -E ':80|:443|:18080'
|
||
docker ps --format 'table {{.Names}}\t{{.Ports}}'
|
||
```
|
||
|
||
## 一键部署
|
||
|
||
```bash
|
||
chmod +x deploy/scripts/*.sh
|
||
|
||
# 首次会生成 deploy/.env.prod 并提示你改域名/公网地址
|
||
./deploy/scripts/deploy.sh
|
||
|
||
# 需要演示账号时（kefu_admin / kefu_admin123 等）
|
||
./deploy/scripts/deploy.sh --seed
|
||
```
|
||
|
||
### 必改配置（`deploy/.env.prod`）
|
||
|
||
| 变量 | 示例 | 说明 |
|
||
|------|------|------|
|
||
| `APP_BASE_URL` | `https://kefu.xx.com` | **浏览器**访问根地址（经 Caddy 时写 https 域名，不要写 `:18080`） |
|
||
| `STORAGE_PUBLIC_BASE_URL` | `https://kefu.xx.com/files` | **必须**与应用内 Nginx `/files` 一致 |
|
||
| `HTTP_PORT` | `18080` | 宿主机映射端口；已有 Caddy 占 80 时用非 80 端口 |
|
||
| `DB_PASSWORD` / `JWT_SECRET` / `STORAGE_*` | 强随机 | 脚本可自动生成密钥 |
|
||
|
||
脚本会校验占位符是否改掉，并在 `HTTP_PORT` 已被占用时告警/退出。
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
./deploy/scripts/deploy.sh --status # 状态
|
||
./deploy/scripts/deploy.sh --down # 停容器（保留卷）
|
||
./deploy/scripts/deploy.sh --seed-only # 仅跑种子
|
||
./deploy/scripts/backup-db.sh # 备份数据库到 ./backups
|
||
|
||
docker compose -f docker-compose.prod.yml --env-file deploy/.env.prod logs -f api
|
||
docker compose -f docker-compose.prod.yml --env-file deploy/.env.prod logs -f web
|
||
```
|
||
|
||
## 与现有 Caddy 共存（同机已有 kefu_sys 等）
|
||
|
||
典型现状：
|
||
|
||
```text
|
||
caddy 0.0.0.0:80→80, 0.0.0.0:443→443
|
||
kefu_sys 仅容器内 8080（由 Caddy 反代）
|
||
```
|
||
|
||
推荐拓扑：
|
||
|
||
```text
|
||
Internet
|
||
└── Caddy :80/:443
|
||
├── 旧域名 → kefu_sys
|
||
└── 新域名 → 127.0.0.1:18080 → kefu-cloud-web(Nginx)
|
||
```
|
||
|
||
### 步骤
|
||
|
||
1. `.env.prod` 设置（示例）：
|
||
|
||
```bash
|
||
HTTP_PORT=18080
|
||
APP_BASE_URL=https://kefu.example.com
|
||
STORAGE_PUBLIC_BASE_URL=https://kefu.example.com/files
|
||
```
|
||
|
||
2. 部署本项目：`./deploy/scripts/deploy.sh`（先确认本机 `curl http://127.0.0.1:18080/healthz` 返回 ok）
|
||
|
||
3. 将 `deploy/caddy/Caddyfile.example` 中的站点段合并进现有 Caddy 配置，把域名改成真实域名后 reload：
|
||
|
||
```bash
|
||
# 示例（按你实际 Caddy 部署方式调整）
|
||
# docker exec caddy caddy validate --config /etc/caddy/Caddyfile
|
||
# docker exec caddy caddy reload --config /etc/caddy/Caddyfile
|
||
```
|
||
|
||
4. 浏览器访问 `https://kefu.example.com`，登录页 `/login`，健康检查 `/health`。
|
||
|
||
### 为何边缘用 Caddy、应用内仍用 Nginx
|
||
|
||
- **Caddy**：你已在用、自动 HTTPS、多站点配置简单，继续当 80/443 入口。
|
||
- **Nginx（web 容器）**：SPA、`/api` WebSocket、`/files`→MinIO 已写好，无需换成 Caddy。
|
||
- **不要**再在宿主机起一个 Nginx 抢 80/443，也**不要**让本 compose 默认绑 80。
|
||
|
||
## HTTPS 其它方式
|
||
|
||
任选其一（与上一节「Caddy 共存」二选一即可）：
|
||
|
||
1. **CLB / CDN** 终结 HTTPS，回源 CVM `HTTP_PORT`（或仍回源 Caddy）
|
||
2. 本机 **Caddy** 反代到 `127.0.0.1:${HTTP_PORT}`（推荐，见上）
|
||
3. 独占机器时 `HTTP_PORT=80`，另用 Nginx + Let’s Encrypt 做 443
|
||
|
||
配置 HTTPS 后，请同步把 `APP_BASE_URL`、`STORAGE_PUBLIC_BASE_URL` 改成 `https://…`。
|
||
|
||
## 使用腾讯云 COS 替代 MinIO（可选）
|
||
|
||
1. 创建 COS 桶，开启公共读或使用 CDN 域名
|
||
2. 在 `.env.prod` 配置 S3 兼容参数（见 `.env.prod.example` 注释）
|
||
3. 从 `docker-compose.prod.yml` 中去掉 `minio` / `minio-init` 依赖，并修改 Nginx，去掉 `/files` 反代（图片直链 COS）
|
||
|
||
当前一键脚本默认 **内置 MinIO**，零额外云产品即可跑通。
|
||
|
||
## 默认种子账号（仅 --seed 后）
|
||
|
||
| 角色 | 用户名 | 密码 |
|
||
|------|--------|------|
|
||
| 平台管理员 | `platform_admin` | `kefu_admin123` |
|
||
| 租户管理员 | `kefu_admin` | `kefu_admin123` |
|
||
| 坐席 | `agent1` 等 | `kefu_admin123` |
|
||
|
||
**上线后立即修改密码或关闭 seed 账号。**
|
||
|
||
## 目录说明
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `docker-compose.prod.yml` | 生产编排 |
|
||
| `deploy/docker/Dockerfile.api` | Go API 镜像 |
|
||
| `deploy/docker/Dockerfile.web` | 前端构建 + Nginx |
|
||
| `deploy/docker/nginx.conf` | 反代与 SPA |
|
||
| `deploy/caddy/Caddyfile.example` | 边缘 Caddy 站点示例（与 80 共存） |
|
||
| `deploy/.env.prod.example` | 环境变量模板 |
|
||
| `deploy/scripts/deploy.sh` | 一键部署 |
|
||
| `deploy/scripts/backup-db.sh` | 数据库备份 |
|
||
|
||
## 故障排查
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| 端口被占用 / bind 失败 | `ss -tlnp` 查占用；改 `HTTP_PORT` 或停冲突容器 |
|
||
| 页面 502 | `docker compose … logs api`，检查 DB 是否 healthy；Caddy 是否指到正确端口 |
|
||
| 图片打不开 | 检查 `STORAGE_PUBLIC_BASE_URL` 是否为 `…/files`，MinIO 桶是否 public download |
|
||
| WebSocket 断 | 确认走同源 `/api/ws`；Caddy 用示例中的 `flush_interval`；CLB 需开启 WebSocket |
|
||
| 构建 Go 失败 | 服务器内存不足时加 swap，或本机 build 后 `docker save` 上传 |
|
||
| 只能本机 18080 访问、域名不通 | Caddy 未 reload / 域名 DNS 未指向本机 / 安全组未放 80/443 |
|
||
|
||
## 升级
|
||
|
||
```bash
|
||
git pull
|
||
./deploy/scripts/backup-db.sh # 升级前建议备份
|
||
./deploy/scripts/deploy.sh # 重新 build 并滚动启动
|
||
```
|