初始版本

2026-04-23 16:30:57 +08:00
commit 0d0683a6e6
538 changed files with 113042 additions and 0 deletions
--- a/content/docs/deploy/docker.md
+++ b/content/docs/deploy/docker.md
@@ -0,0 +1,195 @@
+---
+title: Docker Compose 部署
+description: 一键部署全套服务（前端+后端+数据库+AI），本地与云端通用。
+category: deploy
+order: 1
+---
+
+# Docker Compose 部署
+
+> 一键部署全套服务（前端+后端+数据库+AI），本地与云端通用。
+
+## 🐳 什么是 Docker Compose？
+
+Docker Compose 是一个工具，用于定义和运行多容器 Docker 应用。通过一个 `docker-compose.yml` 文件，你可以一键启动所有相关服务。
+
+## 📋 前提条件
+
+- Docker 20.10+
+- Docker Compose 2.0+
+- 至少 4GB 内存
+
+## 🚀 快速开始
+
+### 第一步：下载模板
+
+```bash
+# 克隆模板仓库
+git clone https://github.com/websopy/deploy-templates.git websopy-deploy
+cd websopy-deploy
+
+# 选择版本
+git checkout v2.3.0
+```
+
+### 第二步：配置环境
+
+```bash
+# 复制环境变量文件
+cp .env.example .env
+
+# 编辑配置
+nano .env
+```
+
+关键配置：
+
+```env
+# 版本
+WEBSOPY_VERSION=2.3.0
+
+# 数据库
+POSTGRES_DB=websopy
+POSTGRES_USER=websopy
+POSTGRES_PASSWORD=your-strong-password
+
+# Redis
+REDIS_PASSWORD=your-redis-password
+
+# JWT 密钥（生成随机字符串）
+JWT_SECRET=$(openssl rand -hex 32)
+
+# 域名（可选）
+DOMAIN=your-domain.com
+```
+
+### 第三步：启动服务
+
+```bash
+# 一键启动所有服务
+docker-compose up -d
+
+# 查看服务状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f
+```
+
+### 第四步：验证部署
+
+```bash
+# 检查服务健康状态
+curl http://localhost:3000/api/health
+
+# 预期输出
+{"status":"ok","version":"2.3.0","services":{"db":"up","redis":"up","ai":"up"}}
+```
+
+## 🏗️ 服务架构
+
+```
+                    ┌─────────────┐
+                    │   Nginx     │
+                    │  (反向代理)   │
+                    └──────┬──────┘
+                           │
+           ┌───────────────┼───────────────┐
+           │               │               │
+      ┌────▼────┐    ┌─────▼────┐    ┌────▼────┐
+      │  Web    │    │   API    │    │  Worker │
+      │ (前端)   │    │ (后端)    │    │ (异步)   │
+      └─────────┘    └─────┬────┘    └─────────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+         ┌────▼───┐  ┌─────▼────┐  ┌───▼────┐
+         │Postgres│  │  Redis   │  │  AI    │
+         │(数据库) │  │ (缓存)    │  │(AI服务) │
+         └────────┘  └──────────┘  └────────┘
+```
+
+## 🔧 常用命令
+
+### 启动与停止
+
+```bash
+# 启动所有服务
+docker-compose up -d
+
+# 停止所有服务
+docker-compose down
+
+# 重启所有服务
+docker-compose restart
+
+# 重启指定服务
+docker-compose restart api
+```
+
+### 日志查看
+
+```bash
+# 查看所有日志
+docker-compose logs -f
+
+# 查看特定服务日志
+docker-compose logs -f api
+docker-compose logs -f web
+
+# 查看最近 100 行
+docker-compose logs --tail=100
+```
+
+### 进入容器
+
+```bash
+# 进入 API 容器
+docker-compose exec api sh
+
+# 进入数据库
+docker-compose exec postgres psql -U websopy
+```
+
+## 💾 数据持久化
+
+数据存储在 Docker volumes 中：
+
+```bash
+# 查看 volumes
+docker volume ls | grep websopy
+
+# 备份数据
+docker-compose exec postgres pg_dump -U websopy > backup.sql
+
+# 恢复数据
+docker exec -i $(docker-compose ps -q postgres) psql -U websopy < backup.sql
+```
+
+## 🐛 故障排查
+
+### 服务无法启动
+
+```bash
+# 1. 检查 Docker 是否运行
+docker info
+
+# 2. 查看详细日志
+docker-compose up
+
+# 3. 检查端口占用
+lsof -i :80
+```
+
+### 数据库连接失败
+
+```bash
+# 1. 检查 postgres 是否运行
+docker-compose ps postgres
+
+# 2. 查看数据库日志
+docker-compose logs postgres
+
+# 3. 测试连接
+docker-compose exec postgres psql -U websopy -c "SELECT 1"
+```
--- a/content/docs/deploy/private-deploy.md
+++ b/content/docs/deploy/private-deploy.md
@@ -0,0 +1,201 @@
+---
+title: 私有化部署完全指南
+description: Docker Compose 一键部署，HTTPS 配置、备份策略与版本升级。
+category: deploy
+order: 2
+---
+
+# 私有化部署完全指南
+
+> 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）
+
+## 🚀 开始部署
+
+### 第一步：准备服务器
+
+```bash
+# 更新系统
+sudo apt update && sudo apt upgrade -y
+
+# 安装 Docker（Ubuntu/Debian）
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+
+# 验证安装
+docker --version
+docker-compose --version
+```
+
+### 第二步：下载部署包
+
+```bash
+# 创建工作目录
+mkdir -p ~/websopy && cd ~/websopy
+
+# 下载最新版本
+wget https://releases.websopy.com/on-premise/latest.tar.gz
+
+# 解压
+tar -xzf latest.tar.gz
+cd websopy-deploy
+```
+
+### 第三步：配置环境
+
+```bash
+# 复制配置文件
+cp .env.example .env
+
+# 编辑配置文件
+nano .env
+```
+
+关键配置项：
+
+```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
+```
+
+### 第四步：启动服务
+
+```bash
+# 拉取镜像
+docker-compose pull
+
+# 启动所有服务
+docker-compose up -d
+
+# 查看服务状态
+docker-compose ps
+```
+
+### 第五步：访问平台
+
+服务启动后，通过浏览器访问：
+
+- 前端界面：`http://your-server-ip:80`
+- 管理后台：`http://your-server-ip:80/admin`
+- API 端点：`http://your-server-ip:8080/api/v1`
+
+## 🔒 HTTPS 配置
+
+### 使用 Let's Encrypt（推荐）
+
+```bash
+# 申请 SSL 证书
+certbot --nginx -d your-domain.com
+
+# 重启 nginx
+docker-compose restart nginx
+```
+
+## 💾 备份策略
+
+### 自动备份脚本
+
+```bash
+#!/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
+
+# 保留最近 30 天的备份
+find $BACKUP_DIR -mtime +30 -delete
+
+echo "备份完成: $DATE"
+```
+
+```bash
+# 设置定时任务（每天凌晨 3 点执行）
+crontab -e
+# 添加行: 0 3 * * * /data/websopy/backup.sh >> /var/log/backup.log 2>&1
+```
+
+## 🐛 常见问题
+
+### Q: 服务启动失败？
+
+```bash
+# 查看日志
+docker-compose logs -f
+
+# 检查端口占用
+netstat -tlnp | grep -E '80|443|5432|6379'
+```
+
+### Q: 内存不足？
+
+```bash
+# 查看内存使用
+docker stats
+
+# 增加 swap
+sudo fallocate -l 4G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
--- a/content/docs/deploy/upgrade.md
+++ b/content/docs/deploy/upgrade.md
@@ -0,0 +1,205 @@
+---
+title: 版本升级与回滚
+description: 平滑升级生产环境，数据库迁移方案，紧急回滚操作手册。
+category: deploy
+order: 3
+---
+
+# 版本升级与回滚
+
+> 平滑升级生产环境，数据库迁移方案，紧急回滚操作手册。
+
+## ⚠️ 升级前必读
+
+### 重要检查清单
+
+- [ ] 备份数据库
+- [ ] 查阅版本更新日志
+- [ ] 在测试环境验证
+- [ ] 确认回滚方案
+- [ ] 通知相关人员
+- [ ] 选择低峰期执行
+
+### 版本兼容性
+
+| 当前版本 | 可直接升级到 |
+|----------|-------------|
+| 2.0.x | 2.1.x |
+| 2.1.x | 2.2.x, 2.3.x |
+| 2.2.x | 2.3.x |
+| 1.x | 需要先升级到 2.0 |
+
+## 🚀 升级步骤
+
+### 准备工作
+
+```bash
+# 1. 进入部署目录
+cd ~/websopy-deploy
+
+# 2. 备份当前版本配置
+cp docker-compose.yml docker-compose.yml.bak
+cp .env .env.bak
+
+# 3. 备份数据库（必须！）
+docker-compose exec postgres pg_dump -U websopy > backups/db_backup_$(date +%Y%m%d).sql
+
+# 4. 备份上传文件
+tar -czf backups/uploads_$(date +%Y%m%d).tar.gz -C /data/websopy uploads/
+```
+
+### 执行升级
+
+```bash
+# 1. 停止服务
+docker-compose down
+
+# 2. 拉取新版本镜像
+docker-compose pull
+
+# 3. 更新代码（如果使用 git 部署）
+git fetch origin
+git checkout v2.3.0
+
+# 4. 检查新版本配置变更
+git diff v2.2.0 v2.3.0 -- .env.example
+
+# 5. 合并配置变更
+nano .env
+
+# 6. 启动服务
+docker-compose up -d
+
+# 7. 执行数据库迁移
+docker-compose run --rm api websopy migrate
+```
+
+### 验证升级
+
+```bash
+# 检查服务状态
+docker-compose ps
+
+# 检查 API 健康
+curl http://localhost:3000/api/health
+
+# 检查版本号
+docker-compose exec api websopy --version
+
+# 查看迁移日志
+docker-compose logs api | grep -i migrate
+```
+
+## 🔧 数据库迁移
+
+### 手动迁移
+
+```bash
+# 查看待执行迁移
+docker-compose run --rm api websopy migrate:status
+
+# 执行迁移
+docker-compose run --rm api websopy migrate
+
+# 回滚上一个迁移
+docker-compose run --rm api websopy migrate:rollback
+```
+
+## ⤵️ 紧急回滚
+
+### 自动回滚
+
+```bash
+# 如果启动失败，查看错误
+docker-compose logs api
+
+# 回滚到上一个版本
+docker-compose down
+git checkout v2.2.0
+docker-compose pull
+docker-compose up -d
+```
+
+### 恢复数据库
+
+```bash
+# 停止服务
+docker-compose down
+
+# 删除新数据库
+docker-compose exec postgres dropdb -U websopy websopy
+
+# 创建空数据库
+docker-compose exec postgres createdb -U websopy websopy
+
+# 恢复备份
+docker exec -i $(docker-compose ps -q postgres) psql -U websopy < backups/db_backup_20240115.sql
+
+# 启动服务
+docker-compose up -d
+```
+
+## 📊 版本更新日志
+
+### v2.3.0（最新）
+
+**新增功能：**
+- 🚀 AI 流式输出优化，延迟降低 50%
+- 📊 新增数据看板组件
+- 🔔 支持自定义 Webhook 事件
+
+**Breaking Changes：**
+- ⚠️ API `/ai/chat` 端点参数变更
+- ⚠️ 环境变量 `AI_MODEL` 重命名为 `DEFAULT_MODEL`
+
+### v2.2.0
+
+**新增功能：**
+- 💬 多语言支持
+- 📱 移动端优化
+- 🔐 SSO 单点登录
+
+### v2.1.0
+
+**新增功能：**
+- 🤖 AI Agent 功能
+- 📚 RAG 知识库
+- ⚡ 工作流自动化
+
+## 🧪 测试环境验证
+
+### 测试清单
+
+- [ ] 首页访问正常
+- [ ] 用户登录/注册
+- [ ] 主要功能操作
+- [ ] API 接口调用
+- [ ] Webhook 接收
+- [ ] 性能无明显下降
+
+## ❓ 常见问题
+
+### Q: 迁移失败怎么办？
+
+1. 停止所有服务
+2. 恢复数据库备份
+3. 检查迁移脚本错误
+4. 联系技术支持
+
+### Q: 镜像拉取失败？
+
+```bash
+# 使用国内镜像源
+nano /etc/docker/daemon.json
+```
+
+```json
+{
+  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
+}
+```
+
+```bash
+sudo systemctl restart docker
+docker-compose pull
+```