wecom_it_smart_desk/docs/09-部署运维/deploy/01-部署指南.md

# 智能IT服务台 - 部署指南

> **最后更新**：2026-07-05
> **目标服务器**：`10.90.5.110`
> **域名**：`itsupport.servyou.com.cn`

---

## 目录

1. [部署流程](#一部署流程)
2. [蓝绿部署](#二蓝绿部署)
3. [故障排查](#三故障排查)
4. [回滚方案](#四回滚方案)

---

## 一、部署流程

### 1.1 前置条件

| 条件 | 状态 | 验证命令 |
|------|------|---------|
| Linux 服务器 10.90.5.110 | ✅ 已确认 | - |
| Docker 已安装 | ✅ 已确认 | `docker --version` |
| 域名解析 | ✅ 已配置 | `nslookup itsupport.servyou.com.cn` |
| 堡垒机可访问 | ✅ 已配置 | `ssh -p 2222 user@10.212.189.210` |

### 1.2 快速部署命令

```bash
# 1. 进入部署目录
cd /opt/wecom-it-desk

# 2. 拉取最新代码（可选）
git pull origin main

# 3. 构建并启动
docker compose up -d --build

# 4. 检查状态
docker ps
```

### 1.3 一键部署（生产环境）

详见 [10-一键部署操作包-v0.7.0.md](./10-一键部署操作包-v0.7.0.md)

### 1.4 部署后验证

```bash
# 检查容器状态
docker ps

# 检查 API 健康
curl https://itsupport.servyou.com.cn/api/health

# 检查日志
docker logs wecom_it_backend --tail 50
```

---

## 二、蓝绿部署

### 2.1 什么是蓝绿部署

蓝绿部署通过维护两套环境（Blue/Green）实现零停机部署和快速回滚。

### 2.2 部署 Green 环境

```bash
cd /opt/wecom-it-desk

# 构建并启动 Green 环境
docker-compose -f docker-compose-green.yml up -d

# 验证 Green 环境
curl http://localhost:5002/health
```

### 2.3 切换流量

```bash
# 切换到 Green
sed -i 's/wecom_it_backend:8000/wecom_it_backend_green:8000/' /opt/wecom-it-desk/nginx/nginx.conf
docker restart wecom_it_nginx

# 切换回 Blue（回滚）
sed -i 's/wecom_it_backend_green:8000/wecom_it_backend:8000/' /opt/wecom-it-desk/nginx/nginx.conf
docker restart wecom_it_nginx
```

### 2.4 端口说明

| 端口 | 服务 |
|------|------|
| 80/443 | Nginx (生产入口) |
| 5002 | Backend (Green) |
| 5080 | Nginx (Green 测试) |

---

## 三、故障排查

### 3.1 常见问题

#### 502 Bad Gateway

1. 检查后端容器是否运行
   ```bash
   docker ps | grep backend
   ```

2. 检查后端日志
   ```bash
   docker logs wecom_it_backend --tail 100
   ```

3. 重启后端
   ```bash
   docker restart wecom_it_backend
   ```

#### 500 错误

详见 [快速诊断-500-错误.md](./快速诊断-500-错误.md)

#### 通讯链路问题

详见 [通讯链路诊断方案.md](./通讯链路诊断方案.md)

### 3.2 健康检查

```bash
# 后端
curl http://localhost:8000/health

# Nginx
curl http://localhost/api/health
```

---

## 四、回滚方案

### 4.1 紧急回滚

如果部署后出现严重问题，立即执行：

```bash
# 1. 停止新版本容器
docker stop wecom_it_backend_green

# 2. 切换回原环境
sed -i 's/wecom_it_backend_green:8000/wecom_it_backend:8000/' /opt/wecom-it-desk/nginx/nginx.conf
docker restart wecom_it_nginx
```

### 4.2 版本回滚

如需回滚到之前版本：

```bash
# 1. 停止当前版本
docker stop wecom_it_backend

# 2. 重新构建指定版本
git checkout <版本标签>
docker build -t wecom-it-desk-backend:<版本> ./backend

# 3. 启动
docker run -d --name wecom_it_backend wecom-it-desk-backend:<版本>
```

---

## 相关文档

- [10-一键部署操作包-v0.7.0.md](./10-一键部署操作包-v0.7.0.md)
- [蓝绿部署指南.md](./蓝绿部署指南.md)
- [快速诊断-500-错误.md](./快速诊断-500-错误.md)
- [通讯链路诊断方案.md](./通讯链路诊断方案.md)
- [12-问题修复记录-20260705.md](./12-问题修复记录-20260705.md)