8.8 KiB
8.8 KiB
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
日常部署流程
前置条件
- SSH 密钥已配置到服务器
- 本地已安装 Python 3.12 + paramiko
快速部署（仅前端改动）
大多数改动只需要重新构建前端并重建 frontend 容器：
# 1. 构建前端
cd frontend
npx vite build
# 2. 部署
cd ..
python deploy/deploy.py
deploy.py 会自动：
- SSH 连接到服务器
- 清理旧的 JS/CSS 文件
- SFTP 上传新的
static/dist/文件 - 执行
docker compose up -d --build frontend
后端改动部署
如果修改了后端代码：
# 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：
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. 服务器准备
# 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. 上传文件
# 在本地上传所有文件
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. 启动服务
ssh root@101.132.183.138 'cd /data/mokee/mokeetext && docker compose up -d --build'
4. 验证
# 检查容器状态
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
常用运维命令
容器管理
# 查看运行状态
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'
日志查看
# 应用日志（按天拆分）
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'
数据库操作
# 进入 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 中。
回滚
如果部署出现问题：
# 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'
故障排查
前端页面空白
- 检查 Nginx 容器是否运行：
docker compose ps frontend - 检查 dist 文件是否存在：
ls /data/mokee/mokeetext/frontend/static/dist/ - 检查 Nginx 日志：
docker compose logs frontend
API 返回 500
- 检查后端容器日志：
docker compose logs backend --tail=100 - 检查数据库连接：确认 MySQL 可访问
- 检查应用日志：
tail -100 /data/mokee/mokeetext/logs/current.log
CORS 错误
- 确认前端请求的 API 地址正确
- 确认
app.py中allow_origins包含当前域名 - 确认请求未经过 Nginx 代理（前端直接调后端）
容器无法启动
# 查看构建日志
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"'