DDUp/docs/deployment-guide.md

Vitals 云服务器部署指南

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

目录

• 准备工作
• 服务器初始化
• 安装 Docker
• 配置防火墙
• 上传项目代码
• 配置环境变量
• 启动服务
• 配置 Nginx
• 配置域名
• 配置 HTTPS
• 自动备份
• 运维命令

---

准备工作

购买云服务器

推荐配置：

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

云厂商选择：

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

购买后记录：

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

---

第一步：服务器初始化

# 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

# 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

---

第三步：配置防火墙

# 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：从本地上传

在本地机器执行：

# 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 仓库拉取

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

---

第五步：配置环境变量

cd /opt/vitals

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

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

# 3. 编辑配置
vim .env

编辑 .env 文件内容：

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

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

默认管理员账号: admin / admin123

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

---

第六步：启动服务

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

# 1. 安装 Nginx
apt install -y nginx

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

配置文件内容：

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";
    }
}

启用配置：

# 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 配置

vim /etc/nginx/sites-available/vitals

将 server_name _; 改为：

server_name vitals.你的域名.com;

重载配置：

nginx -t && systemctl reload nginx

---

第九步：配置 HTTPS

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

# 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 创建备份脚本

vim /opt/vitals/backup.sh

脚本内容：

#!/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 设置定时任务

# 设置执行权限
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 验证备份

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

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

10.4 恢复备份

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

更新部署

cd /opt/vitals

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

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

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

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

资源监控

# 查看容器资源使用
docker stats

# 查看磁盘使用
df -h

# 查看内存使用
free -h

故障排查

# 查看 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 容器是否正常运行：

docker compose ps
docker compose logs

Q: HTTPS 证书申请失败

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

Q: 忘记管理员密码

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

# 进入 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: 数据库损坏

从备份恢复：

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