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