tiantian-system/public/docs/deployment.md

私有化部署完全指南

Docker Compose 一键部署，HTTPS 配置、备份策略与版本升级。

🏠 什么是私有化部署？

私有化部署让你在自己的服务器上运行 Websopy 平台，享受：

• 🔒 数据完全自主 - 所有数据存储在你的服务器
• ⚙️ 完全可控 - 自定义配置、插件、界面
• 💰 成本可控 - 无按调用量计费
• 🏢 合规无忧 - 满足数据不出网要求

📋 系统要求

最低配置

资源	最低要求
CPU	4 核
内存	8 GB
硬盘	100 GB SSD
系统	Ubuntu 20.04+ / CentOS 8+

推荐配置

资源	推荐配置
CPU	8 核+
内存	16 GB+
硬盘	500 GB SSD+
系统	Ubuntu 22.04 LTS

软件依赖

• Docker 20.10+
• Docker Compose 2.0+
• Git
• 域名（可选，用于 HTTPS）

🚀 开始部署

第一步：准备服务器

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

# 安装 Docker（Ubuntu/Debian）
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 安装 Docker Compose
sudo apt install docker-compose -y

# 验证安装
docker --version
docker-compose --version

第二步：下载部署包

# 创建工作目录
mkdir -p ~/websopy && cd ~/websopy

# 下载最新版本
wget https://releases.websopy.com/on-premise/latest.tar.gz

# 解压
tar -xzf latest.tar.gz
cd websopy-deploy

第三步：配置环境

# 复制配置文件
cp .env.example .env

# 编辑配置文件
nano .env

关键配置项：

# 版本配置
WEBSOPY_VERSION=latest

# 数据库配置
DB_HOST=postgres
DB_PORT=5432
DB_NAME=websopy
DB_USER=websopy
DB_PASSWORD=your-secure-password

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

# 域名配置（可选）
DOMAIN=your-domain.com
HTTPS_ENABLED=true

# 管理员账户
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_PASSWORD=your-admin-password

第四步：启动服务

# 拉取镜像
docker-compose pull

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

预期输出：

NAME                STATUS
websopy-app         running
websopy-worker      running
websopy-postgres    running
websopy-redis       running
websopy-nginx       running

第五步：访问平台

服务启动后，通过浏览器访问：

• 前端界面：http://your-server-ip:80
• 管理后台：http://your-server-ip:80/admin
• API 端点：http://your-server-ip:8080/api/v1

首次登录使用配置的 ADMIN_EMAIL 和 ADMIN_PASSWORD。

🔒 HTTPS 配置

使用 Let's Encrypt（推荐）

# 编辑 nginx 配置
nano nginx/conf.d/ssl.conf

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    
    # 其他配置...
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

# 申请 SSL 证书
certbot --nginx -d your-domain.com

# 重启 nginx
docker-compose restart nginx

使用自有证书

# 创建证书目录
mkdir -p nginx/ssl

# 复制证书文件
cp your-cert.crt nginx/ssl/cert.pem
cp your-cert.key nginx/ssl/key.pem

💾 备份策略

自动备份脚本

创建 backup.sh：

#!/bin/bash
BACKUP_DIR=/data/backups/websopy
DATE=$(date +%Y%m%d_%H%M%S)

# 创建备份目录
mkdir -p $BACKUP_DIR

# 备份数据库
docker exec websopy-postgres pg_dump -U websopy > $BACKUP_DIR/db_$DATE.sql

# 备份上传文件
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /data/websopy/uploads

# 备份配置
tar -czf $BACKUP_DIR/config_$DATE.tar.gz /data/websopy/config

# 保留最近 30 天的备份
find $BACKUP_DIR -mtime +30 -delete

echo "备份完成: $DATE"

# 添加执行权限
chmod +x backup.sh

# 设置定时任务（每天凌晨 3 点执行）
crontab -e
# 添加行: 0 3 * * * /data/websopy/backup.sh >> /var/log/backup.log 2>&1

数据恢复

# 停止服务
docker-compose down

# 恢复数据库
docker exec -i websopy-postgres psql -U websopy < db_backup_file.sql

# 恢复上传文件
tar -xzf uploads_backup.tar.gz -C /data/websopy/uploads

# 重启服务
docker-compose up -d

🔄 版本升级

查看当前版本

docker exec websopy-app websopy --version

升级步骤

cd ~/websopy

# 1. 备份当前数据（必须！）
./backup.sh

# 2. 下载新版本
wget https://releases.websopy.com/on-premise/v2.3.0.tar.gz
tar -xzf v2.3.0.tar.gz

# 3. 更新环境变量（如有必要）
nano .env
# 检查新版本的配置变更

# 4. 拉取新镜像
docker-compose pull

# 5. 执行数据库迁移
docker-compose run --rm websopy-app websopy migrate

# 6. 重启服务
docker-compose up -d

# 7. 验证升级
docker-compose logs -f websopy-app

紧急回滚

# 1. 停止当前版本
docker-compose down

# 2. 切换回旧版本
git checkout v2.2.0

# 3. 恢复数据库
docker exec -i websopy-postgres psql -U websopy < db_backup_file.sql

# 4. 启动旧版本
docker-compose up -d

🔧 性能优化

资源调整

编辑 docker-compose.yml：

services:
  websopy-app:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G
  
  websopy-worker:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G

docker-compose up -d

PostgreSQL 优化

docker exec websopy-postgres psql -U websopy -c "
ALTER SYSTEM SET shared_buffers = '2GB';
ALTER SYSTEM SET effective_cache_size = '6GB';
ALTER SYSTEM SET maintenance_work_mem = '512MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
"

docker-compose restart postgres

🐛 常见问题

Q: 服务启动失败？

# 查看日志
docker-compose logs -f

# 检查端口占用
netstat -tlnp | grep -E '80|443|5432|6379'

Q: 数据库连接失败？

1. 检查 DB_PASSWORD 是否正确
2. 确认 postgres 容器是否正常运行
3. 查看 postgres 日志：docker-compose logs postgres

Q: 内存不足？

# 查看内存使用
docker stats

# 增加 swap
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Q: 如何完全卸载？

# 停止服务
docker-compose down -v

# 删除数据（谨慎！）
rm -rf ~/websopy
docker system prune -a

📞 获取帮助

• 📧 邮件支持：support@websopy.com
• 💬 技术社区：forum.websopy.com
• 📖 官方文档：docs.websopy.com

---

上一步： AI 智能体接入指南
下一步： 安装 SDK 与初始化