初始化
This commit is contained in:
310
docs/DEPLOY.md
Normal file
310
docs/DEPLOY.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 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"'
|
||||
```
|
||||
Reference in New Issue
Block a user