311 lines
8.8 KiB
Markdown
311 lines
8.8 KiB
Markdown
# MoKeeText 部署文档
|
||
|
||
## 部署架构
|
||
|
||
```
|
||
Internet
|
||
│
|
||
┌───────┴───────┐
|
||
│ 反向代理/Nginx │ (运维侧管理，SSL 终端)
|
||
└───────┬───────┘
|
||
│
|
||
┌─────────────┼─────────────┐
|
||
│ │ │
|
||
:3006 (前端) :4006 (后端) :3306 (MySQL)
|
||
│ │ │
|
||
┌─────────┴──┐ ┌──────┴──────┐ ┌──┴──────────┐
|
||
│ Nginx │ │ FastAPI │ │ MySQL 8.0 │
|
||
│ (Alpine) │ │ (Python3.12)│ │ (远程) │
|
||
│ │ │ │ │ │
|
||
│ 静态文件 │ │ API + ORM │ │ 10.20.1.122 │
|
||
└────────────┘ └─────────────┘ └──────────────┘
|
||
容器: frontend 容器: backend 外部服务
|
||
```
|
||
|
||
**两个容器**：
|
||
- **frontend** — Nginx Alpine，挂载 Vue 构建产物，端口 3006
|
||
- **backend** — Python 3.12-slim，Uvicorn 运行 FastAPI，端口 4006
|
||
|
||
**跨域通信**：前端直接跨域请求后端 API，Nginx **不代理** `/api/`。CORS 在后端 FastAPI 中配置。
|
||
|
||
---
|
||
|
||
## 环境信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 服务器 IP | `101.132.183.138` |
|
||
| SSH 用户 | `root` |
|
||
| SSH 认证 | 密钥（~/.ssh/id_rsa） |
|
||
| 项目路径 | `/data/mokee/mokeetext` |
|
||
| 前端域名 | `https://mokeetext.zgitm.com` → 端口 `3006` |
|
||
| 后端域名 | `https://mokeetext.server.zgitm.com` → 端口 `4006` |
|
||
| 数据库 | MySQL `10.20.1.122:3306` / 库 `mokeetext` |
|
||
| 数据库用户 | `mokeetext` |
|
||
|
||
---
|
||
|
||
## 服务器目录结构
|
||
|
||
```
|
||
/data/mokee/mokeetext/
|
||
├── docker-compose.yml # 容器编排（由 deploy.py 上传）
|
||
├── backend/
|
||
│ ├── Dockerfile
|
||
│ ├── app.py
|
||
│ ├── models.py
|
||
│ ├── config.py
|
||
│ ├── logger.py
|
||
│ ├── init_db.py
|
||
│ ├── requirements.txt
|
||
│ ├── routes/
|
||
│ │ ├── notes.py
|
||
│ │ ├── websites.py
|
||
│ │ ├── import_api.py
|
||
│ │ ├── upload.py
|
||
│ │ └── share.py
|
||
│ └── middleware/
|
||
│ └── user_context.py
|
||
├── frontend/
|
||
│ ├── Dockerfile.frontend
|
||
│ ├── nginx.conf
|
||
│ └── static/
|
||
│ └── dist/ # Vue 构建产物（Nginx 托管）
|
||
└── logs/ # 应用日志（挂载到宿主机）
|
||
├── mokeetext.log # 按天轮转
|
||
└── current.log
|
||
```
|
||
|
||
---
|
||
|
||
## 日常部署流程
|
||
|
||
### 前置条件
|
||
|
||
1. SSH 密钥已配置到服务器
|
||
2. 本地已安装 Python 3.12 + paramiko
|
||
|
||
### 快速部署（仅前端改动）
|
||
|
||
大多数改动只需要重新构建前端并重建 frontend 容器：
|
||
|
||
```bash
|
||
# 1. 构建前端
|
||
cd frontend
|
||
npx vite build
|
||
|
||
# 2. 部署
|
||
cd ..
|
||
python deploy/deploy.py
|
||
```
|
||
|
||
`deploy.py` 会自动：
|
||
1. SSH 连接到服务器
|
||
2. 清理旧的 JS/CSS 文件
|
||
3. SFTP 上传新的 `static/dist/` 文件
|
||
4. 执行 `docker compose up -d --build frontend`
|
||
|
||
### 后端改动部署
|
||
|
||
如果修改了后端代码：
|
||
|
||
```bash
|
||
# 1. 上传后端文件
|
||
scp backend/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/
|
||
scp backend/routes/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/routes/
|
||
scp backend/middleware/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/middleware/
|
||
|
||
# 2. 重建后端容器
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build backend'
|
||
```
|
||
|
||
### Docker Compose 配置变更
|
||
|
||
如果修改了 `docker-compose.yml`：
|
||
|
||
```bash
|
||
scp deploy/docker-compose.yml root@101.132.183.138:/data/mokee/mokeetext/docker-compose.yml
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build'
|
||
```
|
||
|
||
---
|
||
|
||
## 首次部署（从零搭建）
|
||
|
||
### 1. 服务器准备
|
||
|
||
```bash
|
||
# SSH 到服务器
|
||
ssh root@101.132.183.138
|
||
|
||
# 安装 Docker（如果尚未安装）
|
||
curl -fsSL https://get.docker.com | sh
|
||
|
||
# 创建项目目录
|
||
mkdir -p /data/mokee/mokeetext/{backend/routes,backend/middleware,frontend/static/dist,logs}
|
||
```
|
||
|
||
### 2. 上传文件
|
||
|
||
```bash
|
||
# 在本地上传所有文件
|
||
scp deploy/docker-compose.yml root@101.132.183.138:/data/mokee/mokeetext/
|
||
|
||
scp backend/*.py backend/*.txt backend/Dockerfile backend/.dockerignore \
|
||
root@101.132.183.138:/data/mokee/mokeetext/backend/
|
||
|
||
scp backend/routes/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/routes/
|
||
scp backend/middleware/*.py root@101.132.183.138:/data/mokee/mokeetext/backend/middleware/
|
||
|
||
scp frontend/Dockerfile.frontend frontend/nginx.conf frontend/.dockerignore \
|
||
root@101.132.183.138:/data/mokee/mokeetext/frontend/
|
||
|
||
# 构建前端并上传
|
||
cd frontend && npx vite build && cd ..
|
||
scp -r frontend/static/dist/* root@101.132.183.138:/data/mokee/mokeetext/frontend/static/dist/
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build'
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
```bash
|
||
# 检查容器状态
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose ps'
|
||
|
||
# 检查后端健康
|
||
curl https://mokeetext.server.zgitm.com/api/notes
|
||
|
||
# 检查前端
|
||
curl https://mokeetext.zgitm.com
|
||
```
|
||
|
||
---
|
||
|
||
## 常用运维命令
|
||
|
||
### 容器管理
|
||
|
||
```bash
|
||
# 查看运行状态
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose ps'
|
||
|
||
# 查看日志
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose logs --tail=50 backend'
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose logs --tail=50 frontend'
|
||
|
||
# 重启单个服务
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose restart backend'
|
||
|
||
# 停止所有服务
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose down'
|
||
|
||
# 完全重建（清除缓存）
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose build --no-cache && docker compose up -d'
|
||
```
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# 应用日志（按天拆分）
|
||
ssh root@101.132.183.138 'ls -la /data/mokee/mokeetext/logs/'
|
||
ssh root@101.132.183.138 'tail -100 /data/mokee/mokeetext/logs/current.log'
|
||
|
||
# 实时跟踪
|
||
ssh root@101.132.183.138 'tail -f /data/mokee/mokeetext/logs/current.log'
|
||
```
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 进入 MySQL
|
||
ssh root@101.132.183.138 'docker exec -it mokeetext-backend-1 python -c "
|
||
import pymysql
|
||
conn = pymysql.connect(host=\"10.20.1.122\", user=\"mokeetext\", password=\"mokee.\", database=\"mokeetext\")
|
||
print(\"connected\")
|
||
conn.close()
|
||
"'
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
### Backend 容器
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `MYSQL_HOST` | `10.20.1.122` | 数据库主机 |
|
||
| `MYSQL_PORT` | `3306` | 数据库端口 |
|
||
| `MYSQL_USER` | `mokeetext` | 数据库用户 |
|
||
| `MYSQL_PASSWORD` | `mokee.` | 数据库密码 |
|
||
| `MYSQL_DATABASE` | `mokeetext` | 数据库名 |
|
||
| `LOG_DIR` | `/data/mokee/mokeetext/logs` | 日志目录 |
|
||
|
||
这些在 `docker-compose.yml` 中定义，可通过 `.env` 文件覆盖。
|
||
|
||
### Frontend 构建
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `VITE_API_BASE` | 生产环境 API 地址 |
|
||
| `VITE_LOGIN_URL` | 统一登录页地址 |
|
||
| `VITE_SYSTEM_CODE` | 系统编码 |
|
||
|
||
定义在 `frontend/.env.production` 中。
|
||
|
||
---
|
||
|
||
## 回滚
|
||
|
||
如果部署出现问题：
|
||
|
||
```bash
|
||
# 1. 回到上一个前端镜像
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d frontend'
|
||
# Docker 会使用缓存的镜像层
|
||
|
||
# 2. 如果有备份的 dist 文件
|
||
scp backup-dist/* root@101.132.183.138:/data/mokee/mokeetext/frontend/static/dist/
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose restart frontend'
|
||
|
||
# 3. 极端情况：重建所有容器
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose down && docker compose up -d --build'
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 前端页面空白
|
||
|
||
1. 检查 Nginx 容器是否运行：`docker compose ps frontend`
|
||
2. 检查 dist 文件是否存在：`ls /data/mokee/mokeetext/frontend/static/dist/`
|
||
3. 检查 Nginx 日志：`docker compose logs frontend`
|
||
|
||
### API 返回 500
|
||
|
||
1. 检查后端容器日志：`docker compose logs backend --tail=100`
|
||
2. 检查数据库连接：确认 MySQL 可访问
|
||
3. 检查应用日志：`tail -100 /data/mokee/mokeetext/logs/current.log`
|
||
|
||
### CORS 错误
|
||
|
||
1. 确认前端请求的 API 地址正确
|
||
2. 确认 `app.py` 中 `allow_origins` 包含当前域名
|
||
3. 确认请求未经过 Nginx 代理（前端直接调后端）
|
||
|
||
### 容器无法启动
|
||
|
||
```bash
|
||
# 查看构建日志
|
||
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose build --progress=plain'
|
||
|
||
# 检查端口占用
|
||
ssh root@101.132.183.138 'netstat -tlnp | grep -E "3006|4006"'
|
||
```
|