mokee/mokeeText
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mokeeText/docs/DEPLOY.md
zg 4e0057ece5 初始化
2026-07-15 16:08:17 +08:00

8.8 KiB
Raw Permalink Blame History

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 容器：

# 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

后端改动部署

如果修改了后端代码：

# 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'

故障排查

前端页面空白

  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 代理（前端直接调后端）

容器无法启动

# 查看构建日志
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 View Git Blame Copy Permalink