012-kaopeilian/backend/deploy/server_setup_guide.md

考陪练系统 SQL 执行器服务器部署指南

服务器信息

• IP地址: 120.79.247.16
• 域名: aiedu.ireborn.com.cn
• 端口: 8000
• 数据库: MySQL (已配置在同一服务器)

部署步骤

1. 连接到服务器

ssh root@120.79.247.16

2. 准备环境

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

# 安装 Python 3.9+
apt install python3 python3-pip python3-venv -y

# 安装 MySQL 客户端（如果需要）
apt install mysql-client -y

# 安装 Git
apt install git -y

# 创建应用目录
mkdir -p /opt/kaopeilian
cd /opt/kaopeilian

3. 克隆或上传代码

# 如果使用 Git
git clone <your-repo-url> backend
cd backend

# 或者使用 scp 上传
# 在本地执行：
# scp -r /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend root@120.79.247.16:/opt/kaopeilian/backend

4. 创建虚拟环境和安装依赖

cd /opt/kaopeilian/backend

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 升级 pip
pip install --upgrade pip

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

5. 配置环境变量

创建 .env 文件：

cat > .env << EOF
# 应用配置
APP_NAME=KaoPeiLian
DEBUG=False
HOST=0.0.0.0
PORT=8000

# 数据库配置
DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025!@#@localhost:3306/kaopeilian?charset=utf8mb4

# Redis配置（如果有）
REDIS_URL=redis://localhost:6379/0

# JWT配置
SECRET_KEY=your-production-secret-key-at-least-32-chars
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS配置
CORS_ORIGINS=["http://120.79.247.16:8000", "http://aiedu.ireborn.com.cn", "http://localhost:3000"]

# 日志配置
LOG_LEVEL=INFO
LOG_FORMAT=json
EOF

6. 创建 systemd 服务

cat > /etc/systemd/system/kaopeilian-backend.service << EOF
[Unit]
Description=KaoPeiLian Backend API
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/kaopeilian/backend
Environment="PATH=/opt/kaopeilian/backend/venv/bin"
ExecStart=/opt/kaopeilian/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

7. 启动服务

# 重新加载 systemd
systemctl daemon-reload

# 启用服务（开机自启）
systemctl enable kaopeilian-backend

# 启动服务
systemctl start kaopeilian-backend

# 查看服务状态
systemctl status kaopeilian-backend

# 查看日志
journalctl -u kaopeilian-backend -f

8. 配置防火墙

# 如果使用 ufw
ufw allow 8000/tcp
ufw reload

# 如果使用 iptables
iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
iptables-save > /etc/iptables/rules.v4

9. 测试部署

# 健康检查
curl http://localhost:8000/health

# 测试 SQL 执行器（简化认证）
curl -X POST http://localhost:8000/api/v1/sql/execute-simple \
  -H "X-API-Key: dify-2025-kaopeilian" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT COUNT(*) as total FROM users"
  }'

更新部署

# 进入项目目录
cd /opt/kaopeilian/backend

# 拉取最新代码（如果使用 Git）
git pull

# 或者重新上传文件

# 重启服务
systemctl restart kaopeilian-backend

日志和监控

查看实时日志

journalctl -u kaopeilian-backend -f

查看错误日志

journalctl -u kaopeilian-backend -p err -n 100

检查服务状态

systemctl status kaopeilian-backend

故障排除

1. 服务无法启动

# 检查 Python 路径
which python3

# 检查虚拟环境
ls -la /opt/kaopeilian/backend/venv/bin/

# 手动测试启动
cd /opt/kaopeilian/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

2. 数据库连接失败

# 测试数据库连接
mysql -h localhost -u root -p'Kaopeilian2025!@#' -e "SELECT 1"

# 检查数据库服务
systemctl status mysql

3. 端口被占用

# 查看端口占用
netstat -tlnp | grep 8000

# 或
lsof -i :8000

性能优化（可选）

使用 Gunicorn + Uvicorn

# 安装 gunicorn
pip install gunicorn

# 修改服务文件的 ExecStart
ExecStart=/opt/kaopeilian/backend/venv/bin/gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

使用 Nginx 反向代理

# 安装 Nginx
apt install nginx -y

# 配置 Nginx
cat > /etc/nginx/sites-available/kaopeilian << EOF
server {
    listen 80;
    server_name aiedu.ireborn.com.cn;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
    }
}
EOF

# 启用配置
ln -s /etc/nginx/sites-available/kaopeilian /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

安全建议

1. 修改默认 API Key：编辑 /opt/kaopeilian/backend/app/core/simple_auth.py
2. 使用 HTTPS：配置 SSL 证书
3. 限制 IP 访问：只允许 Dify 服务器访问
4. 定期备份：数据库和代码
5. 监控日志：及时发现异常

Dify 配置

部署完成后，在 Dify 中使用：

• URL: http://120.79.247.16:8000/api/v1/sql/execute-simple
• 认证方式: 请求头
• X-API-Key: dify-2025-kaopeilian