DDUp/docs/deployment-guide.md

# Vitals 云服务器部署指南

本指南详细介绍如何将 Vitals 部署到云服务器，实现公网访问。

## 目录

- [准备工作](#准备工作)
- [服务器初始化](#第一步服务器初始化)
- [安装 Docker](#第二步安装-docker)
- [配置防火墙](#第三步配置防火墙)
- [上传项目代码](#第四步上传项目代码)
- [配置环境变量](#第五步配置环境变量)
- [启动服务](#第六步启动服务)
- [配置 Nginx](#第七步安装配置-nginx)
- [配置域名](#第八步配置域名)
- [配置 HTTPS](#第九步配置-https)
- [自动备份](#第十步配置自动备份)
- [运维命令](#常用运维命令)

---

## 准备工作

### 购买云服务器

**推荐配置：**

| 配置项 | 推荐值 |
|--------|--------|
| CPU | 1核 |
| 内存 | 2GB |
| 硬盘 | 40GB SSD |
| 系统 | Ubuntu 22.04 LTS |
| 带宽 | 1-5Mbps |

**云厂商选择：**

| 厂商 | 价格参考 | 特点 |
|------|----------|------|
| 阿里云 | ~¥50/月 | 国内访问快，需备案 |
| 腾讯云 | ~¥45/月 | 国内访问快，需备案 |
| Vultr/DigitalOcean | ~$6/月 | 无需备案，海外访问 |
| Bandwagon | ~$50/年 | 便宜，适合个人 |

**购买后记录：**

- 服务器公网 IP: `_______________`
- SSH 端口: `22`
- root 密码或 SSH 密钥

---

## 第一步：服务器初始化

```bash
# 1. SSH 登录服务器
ssh root@你的服务器IP

# 2. 更新系统
apt update && apt upgrade -y

# 3. 设置时区
timedatectl set-timezone Asia/Shanghai

# 4. 安装常用工具
apt install -y vim curl wget git unzip
```

---

## 第二步：安装 Docker

```bash
# 1. 安装 Docker
curl -fsSL https://get.docker.com | sh

# 2. 启动并设置开机自启
systemctl start docker
systemctl enable docker

# 3. 验证安装
docker --version

# 4. 安装 Docker Compose 插件
apt install -y docker-compose-plugin

# 5. 验证
docker compose version
```

---

## 第三步：配置防火墙

```bash
# 1. 安装 ufw
apt install -y ufw

# 2. 配置规则
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS

# 3. 启用防火墙
ufw enable

# 4. 查看状态
ufw status
```

---

## 第四步：上传项目代码

### 方式 A：从本地上传

在本地机器执行：

```bash
# 1. 打包项目（排除不需要的文件）
cd /path/to/vitals
tar -czvf vitals.tar.gz \
    --exclude='.git' \
    --exclude='data' \
    --exclude='__pycache__' \
    --exclude='.coverage' \
    --exclude='*.pyc' \
    --exclude='.DS_Store' \
    .

# 2. 上传到服务器
scp vitals.tar.gz root@你的服务器IP:/opt/

# 3. SSH 登录服务器解压
ssh root@你的服务器IP
cd /opt
mkdir -p vitals
tar -xzvf vitals.tar.gz -C vitals
rm vitals.tar.gz
```

### 方式 B：从 Git 仓库拉取

```bash
ssh root@你的服务器IP
cd /opt
git clone https://github.com/你的用户名/vitals.git
```

---

## 第五步：配置环境变量

```bash
cd /opt/vitals

# 1. 复制模板
cp .env.example .env

# 2. 生成 JWT 密钥
openssl rand -hex 32
# 记录输出的随机字符串

# 3. 编辑配置
vim .env
```

编辑 `.env` 文件内容：

```bash
# JWT 密钥<E5AF86><E992A5>粘贴上面生成的随机字符串）
JWT_SECRET=粘贴上面生成的64位随机字符串

# AI 食物识别（可选）
DASHSCOPE_API_KEY=
DEEPSEEK_API_KEY=
```

**默认管理员账号**: `admin` / `admin123`

> 部署后请立即登录并修改默认密码！

---

## 第六步：启动服务

```bash
cd /opt/vitals

# 1. 创建数据目录
mkdir -p /opt/vitals/data
chmod 755 /opt/vitals/data

# 2. 创建 MySQL 数据目录（宿主机存储）
mkdir -p /opt/vitals/mysql_data
# MySQL 容器需要写权限，设置为 777 或使用特定用户
chmod 777 /opt/vitals/mysql_data

# 3. 构建并启动
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

# 4. 查看运行状态
docker compose ps

# 5. 查看日志
docker compose logs -f

# 6. 测试是否正常运行
curl http://localhost:8080/api/today
```

如果看到 JSON 响应，说明服务已正常运行。

---

## 第七步：安装配置 Nginx

```bash
# 1. 安装 Nginx
apt install -y nginx

# 2. 创建站点配置
vim /etc/nginx/sites-available/vitals
```

配置文件内容：

```nginx
server {
    listen 80;
    server_name _;  # 先用下划线表示匹配所有，后面改成域名

    # 文件上传大小限制
    client_max_body_size 10M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持（如需要）
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

启用配置：

```bash
# 3. 创建软链接启用站点
ln -s /etc/nginx/sites-available/vitals /etc/nginx/sites-enabled/

# 4. 删除默认站点（可选）
rm /etc/nginx/sites-enabled/default

# 5. 测试配置
nginx -t

# 6. 重载 Nginx
systemctl reload nginx

# 7. 设置开机自启
systemctl enable nginx
```

**测试访问：**

浏览器打开 `http://你的服务器IP`，应该能看到 Vitals 首页。

---

## 第八步：配置域名

### 8.1 购买/准备域名

- 国内服务器需要备案域名
- 海外服务器可用未备案域名

### 8.2 添加 DNS 解析

在域名服务商控制台添加 A 记录：

| 主机记录 | 记录类型 | 记录值 |
|----------|----------|--------|
| vitals | A | 你的服务器IP |

等待 DNS 生效（通常几分钟到几小时）。

### 8.3 更新 Nginx 配置

```bash
vim /etc/nginx/sites-available/vitals
```

将 `server_name _;` 改为：

```nginx
server_name vitals.你的域名.com;
```

重载配置：

```bash
nginx -t && systemctl reload nginx
```

---

## 第九步：配置 HTTPS

**强烈推荐**：生产环境必须启用 HTTPS。

```bash
# 1. 安装 Certbot
apt install -y certbot python3-certbot-nginx

# 2. 申请证书（自动配置 Nginx）
certbot --nginx -d vitals.你的域名.com

# 按提示操作：
# - 输入邮箱
# - 同意条款
# - 选择是否重定向 HTTP 到 HTTPS（推荐选 2）

# 3. 验证自动续期
certbot renew --dry-run

# 4. 查看证书状态
certbot certificates
```

证书会自动续期，Certbot 会创建 systemd timer 处理。

---

## 第十步：配置自动备份

### 10.1 创建备份脚本

```bash
vim /opt/vitals/backup.sh
```

脚本内容：

```bash
#!/bin/bash
BACKUP_DIR="/opt/vitals/backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# 方式1: 使用 mysqldump 导出 SQL（推荐）
docker compose exec -T mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD:-rootpassword} vitals > $BACKUP_DIR/vitals_$DATE.sql

# 方式2: 直接复制 mysql_data 目录（完整备份）
# tar -czf $BACKUP_DIR/mysql_data_$DATE.tar.gz -C /opt/vitals mysql_data

# 保留最近 7 天的备份
find $BACKUP_DIR -name "vitals_*.sql" -mtime +7 -delete

echo "$(date): Backup completed - vitals_$DATE.sql"
```

### 10.2 设置定时任务

```bash
# 设置执行权限
chmod +x /opt/vitals/backup.sh

# 添加定时任务（每天凌晨 3 点备份）
crontab -e
```

添加一行：

```
0 3 * * * cd /opt/vitals && ./backup.sh >> /var/log/vitals-backup.log 2>&1
```

### 10.3 验证备份

```bash
# 手动执行一次
cd /opt/vitals && ./backup.sh

# 查看备份文件
ls -la /opt/vitals/backups/
```

### 10.4 恢复备份

```bash
# 从 SQL 文件恢复
docker compose exec -T mysql mysql -u root -p${MYSQL_ROOT_PASSWORD:-rootpassword} vitals < /opt/vitals/backups/vitals_20260123_120000.sql

# 或从 tar.gz 恢复（完整恢复）
# tar -xzf /opt/vitals/backups/mysql_data_20260123_120000.tar.gz -C /opt/vitals
# docker compose restart
```

# 查看备份文件
ls -la /opt/vitals/backups/
```

---

## 常用运维命令

### 服务管理

```bash
cd /opt/vitals

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 查看最近 100 行日志
docker compose logs --tail 100

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 启动服务
docker compose up -d
```

### 更新部署

```bash
cd /opt/vitals

# 1. 备份数据
./backup.sh

# 2. 拉取新代码（如果用 Git）
git pull

# 3. 重新构建并启动
docker compose down
docker compose up -d --build

# 4. 查看日志确认正常
docker compose logs -f
```

### 资源监控

```bash
# 查看容器资源使用
docker stats

# 查看磁盘使用
df -h

# 查看内存使用
free -h
```

### 故障排查

```bash
# 查看 Nginx 错误日志
tail -f /var/log/nginx/error.log

# 查看应用日志
docker compose logs -f

# 进入容器调试
docker compose exec vitals /bin/bash

# 检查端口占用
ss -tlnp | grep 8080
```

---

## 部署完成检查清单

| 检查项 | 命令/操作 | 预期结果 |
|--------|-----------|----------|
| 服务运行 | `docker compose ps` | 状态为 running |
| MySQL 数据目录 | `ls -la /opt/vitals/mysql_data/` | 有数据文件 |
| API 响应 | `curl localhost:8080/api/today` | 返回 JSON |
| HTTP 访问 | 浏览器打开 `http://IP` | 显示首页 |
| HTTPS 访问 | 浏览器打开 `https://域名` | 显示首页，有锁图标 |
| 登录功能 | 访问 `/login` 用 admin 登录 | 登录成功 |
| 管理后台 | 访问 `/admin` | 显示管理面板 |
| 备份脚本 | `ls -la /opt/vitals/backup.sh` | 文件存在且可执行 |

---

## 安全检查清单

| 项目 | 要求 |
|------|------|
| 管理员密码 | 部署后立即修改默认密码 (admin/admin123) |
| JWT 密钥 | 使用 `openssl rand -hex 32` 生成的随机字符串 |
| HTTPS | 生产环境必须启用 |
| 防火墙 | 只开放必要端口 (22, 80, 443) |
| SSH | 建议禁用密码登录，使用密钥认证 |
| 定期备份 | 配置 cron 定时备份数据库 |
| 系统更新 | 定期执行 `apt update && apt upgrade` |

---

## 最终访问地址

部署完成后，可通过以下地址访问：

| 页面 | 地址 |
|------|------|
| 首页 | `https://vitals.你的域名.com` |
| 登录 | `https://vitals.你的域名.com/login` |
| 注册 | `https://vitals.你的域名.com/register` |
| 管理后台 | `https://vitals.你的域名.com/admin` |

---

## 其他部署方案

如果不想使用云服务器，还可以考虑以下方案：

### 内网穿透（临时测试）

- **Cloudflare Tunnel** - 免费，需要域名托管在 Cloudflare
- **ngrok** - 简单快速，免费版有限制

### PaaS 平台（零运维）

- **Railway.app** - 简单易用，有免费额度
- **Fly.io** - 全球部署，有免费额度
- **Render** - 自动部署，有免费额度

---

## 常见问题

### Q: 访问显示 502 Bad Gateway

检查 Docker 容器是否正常运行：
```bash
docker compose ps
docker compose logs
```

### Q: HTTPS 证书申请失败

1. 确认域名 DNS 已生效：`nslookup vitals.你的域名.com`
2. 确认 80 端口可访问
3. 确认 Nginx 配置正确

### Q: 忘记管理员密码

管理员密码存储在 MySQL 数据库中，可以通过以下方式重置：

```bash
# 进入 MySQL 容器
docker compose exec mysql mysql -u root -p

# 选择数据库
use vitals;

# 生成新的密码哈希（Python）
# python -c "import bcrypt; print(bcrypt.hashpw(b'newpassword', bcrypt.gensalt()).decode())"

# 更新管理员密码（将下方哈希值替换为生成的）
UPDATE users SET password_hash = '$2b$12$...' WHERE name = 'admin';
```

### Q: 数据库损坏

从备份恢复：
```bash
# 从 SQL 备份恢复
docker compose exec -T mysql mysql -u root -p${MYSQL_ROOT_PASSWORD:-rootpassword} vitals < /opt/vitals/backups/vitals_20260123_120000.sql

# 或直接复制数据目录恢复（需要重启）
# tar -xzf /opt/vitals/backups/mysql_data_20260123_120000.tar.gz -C /opt/vitals
# docker compose restart
```

---

*最后更新: 2026-01-23*