VPS 部署指南

在生产环境部署 Huper 琥珀，适合长期使用和多用户访问。

---

📦 前置要求

要求	配置	说明
VPS	1GB+ RAM	Ubuntu 20.04+
域名	可选	用于 HTTPS
SSL 证书	可选	Let's Encrypt
Cloudflare	推荐	CDN + 防护

---

🚀 快速部署

第一步：准备服务器

# SSH 登录
ssh root@your-vps-ip

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

# 安装依赖
apt install -y python3 python3-pip python3-venv nginx git

第二步：克隆代码

# 创建应用目录
mkdir -p /var/www/huper
cd /var/www/huper

# 克隆仓库
git clone https://github.com/ankechenlab-node/huper.git .

第三步：安装依赖

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 安装 Gunicorn（生产服务器）
pip install gunicorn

第四步：初始化数据库

# 创建数据目录
mkdir -p data

# 初始化数据库
python init_db.py

第五步：配置环境变量

# 创建 .env 文件
cat > .env << EOF
DATABASE_URL=sqlite:///data/huper.db
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
FLASK_ENV=production
EOF

---

🔧 系统服务配置

创建 systemd 服务

cat > /etc/systemd/system/huper.service << EOF
[Unit]
Description=Huper Amber Service
After=network.target

[Service]
Type=notify
User=www-data
Group=www-data
WorkingDirectory=/var/www/huper
Environment="PATH=/var/www/huper/venv/bin"
ExecStart=/var/www/huper/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 app:app
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# 重载 systemd
systemctl daemon-reload

# 启动服务
systemctl start huper
systemctl enable huper

# 检查状态
systemctl status huper

Nginx 反向代理

cat > /etc/nginx/sites-available/huper << EOF
server {
    listen 80;
    server_name huper.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        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;
    }

    location /static {
        alias /var/www/huper/static;
        expires 30d;
    }
}
EOF

# 启用配置
ln -s /etc/nginx/sites-available/huper /etc/nginx/sites-enabled/

# 测试配置
nginx -t

# 重载 Nginx
systemctl reload nginx

---

🔒 HTTPS 配置（推荐）

使用 Let's Encrypt

# 安装 Certbot
apt install -y certbot python3-certbot-nginx

# 获取证书
certbot --nginx -d huper.your-domain.com

# 自动续期
certbot renew --dry-run

Cloudflare 配置

1. 添加域名到 Cloudflare
2. 开启 SSL/TLS → Full
3. 配置 DNS A 记录指向 VPS IP
4. 开启 CDN 加速

---

📊 监控与维护

日志查看

# 应用日志
journalctl -u huper -f

# Nginx 日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

# 系统日志
journalctl -f

备份策略

# 创建备份脚本
cat > /usr/local/bin/huper-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backups/huper"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p $BACKUP_DIR
cp /var/www/huper/data/huper.db $BACKUP_DIR/huper-$DATE.db
find $BACKUP_DIR -name "*.db" -mtime +30 -delete
EOF

chmod +x /usr/local/bin/huper-backup.sh

# 添加 cron 任务（每天凌晨 3 点）
echo "0 3 * * * /usr/local/bin/huper-backup.sh" >> /etc/crontab

健康检查

# 创建健康检查脚本
cat > /usr/local/bin/huper-health.sh << 'EOF'
#!/bin/bash
if ! systemctl is-active --quiet huper; then
    echo "Huper service is down!"
    systemctl restart huper
fi
EOF

chmod +x /usr/local/bin/huper-health.sh

# 每 5 分钟检查一次
echo "*/5 * * * * /usr/local/bin/huper-health.sh" >> /etc/crontab

---

🐛 故障排查

服务启动失败

# 检查日志
journalctl -u huper -n 50

# 常见原因：
# 1. 端口占用：lsof -i :5000
# 2. 权限问题：chown -R www-data:www-data /var/www/huper
# 3. 依赖缺失：pip install -r requirements.txt

数据库锁定

# 检查数据库锁
lsof /var/www/huper/data/huper.db

# 解决方法：重启服务
systemctl restart huper

内存不足

# 检查内存使用
free -h

# 减少 Gunicorn worker 数量
# 编辑 /etc/systemd/system/huper.service
# 修改 -w 4 为 -w 2

---

📚 下一步

• 配置优化 - 高级配置项
• 数据备份 - 备份策略详解
• 故障排查 - 常见问题解决

---

提示：部署完成后，访问 https://huper.your-domain.com 测试。