diff --git a/DEPLOY.md b/DEPLOY.md deleted file mode 100644 index 7c67d59..0000000 --- a/DEPLOY.md +++ /dev/null @@ -1,605 +0,0 @@ -# 云升数码 - 部署教程 - -> 一文搞定从零到线上的完整部署流程，支持 Linux / Windows / Docker 三种方式 - ---- - -## 📋 目录 - -- [准备工作](#准备工作) -- [方式一：Linux 一键部署（推荐）](#方式一linux-一键部署推荐) -- [方式二：Windows 部署](#方式二windows-部署) -- [方式三：Docker 容器化部署](#方式三docker-容器化部署) -- [域名与 SSL 配置](#域名与-ssl-配置) -- [后台初始化](#后台初始化) -- [常用维护命令](#常用维护命令) -- [故障排查](#故障排查) -- [进阶配置](#进阶配置) - ---- - -## 🎯 准备工作 - -### 服务器要求 - -| 组件 | 最低配置 | 推荐配置 | -|------|----------|----------| -| CPU | 1 核 | 2 核+ | -| 内存 | 1 GB | 2 GB+ | -| 硬盘 | 10 GB | 50 GB+ (SSD) | -| 系统 | Ubuntu 22.04+ / Debian 12+ / CentOS 9+ / Windows Server 2019+ | Ubuntu 24.04 LTS | -| 带宽 | 5 Mbps | 20 Mbps+ | - -### 必备条件 - -- ✅ 一台云服务器（腾讯云/阿里云/华为云/轻量应用服务器均可） -- ✅ 一个已备案域名（中国大陆节点必须备案） -- ✅ 域名已解析到服务器公网 IP（A 记录） -- ✅ SSH 客户端（Windows 推荐 Terminal / Tabby，Mac/Linux 自带 Terminal） - ---- - -## 🚀 方式一：Linux 一键部署（推荐） - -### 适用系统 - -- Ubuntu 22.04 / 24.04 LTS -- Debian 12 (Bookworm) -- CentOS / Rocky Linux / AlmaLinux 9+ - -### 步骤 1：连接服务器 - -```bash -# 使用 SSH 连接（替换为你的服务器 IP） -ssh root@your-server-ip - -# 或使用密钥登录 -ssh -i ~/.ssh/id_rsa root@your-server-ip -``` - -### 步骤 2：下载并运行安装脚本 - -```bash -# 1. 克隆项目仓库 -git clone https://git.grxiao.cn/yuns/plerr-open.git -cd plerr-open - -# 2. 赋予脚本执行权限 -chmod +x scripts/install.sh - -# 3. 运行一键安装（需要 root 权限） -sudo ./scripts/install.sh -``` - -### 步骤 3：按提示输入信息 - -脚本会交互式询问： - -```bash -请输入域名 (例: yunsheng.digital): your-domain.com -请输入邮箱 (用于 SSL 证书): admin@your-domain.com -``` - -> 💡 **提示**：如果不想交互，可直接传参： -> ```bash -> sudo ./scripts/install.sh your-domain.com admin@your-domain.com -> ``` - -### 步骤 4：等待部署完成 - -脚本会自动完成以下工作（约 3-5 分钟）： - -1. 📦 安装系统依赖 -2. ⬇️ 下载 PocketBase v0.22.0 -3. ⚙️ 配置 systemd 服务 -4. 🌐 配置 Nginx 反向代理 -5. 🔒 申请 Let's Encrypt SSL 证书 -6. 🛡️ 配置防火墙 & Fail2Ban -7. 📝 创建维护脚本 & 定时任务 -8. 🚀 启动所有服务 - -### 步骤 5：访问验证 - -部署成功后会显示： - -```bash -========================================== - 部署完成！ -========================================== - -📋 重要信息： - - 网站地址: https://your-domain.com - - 后台管理: https://your-domain.com/_/ - - 管理员账号: admin@yunsheng.digital - - 管理员密码: YunSheng@2024!Admin - - PocketBase 数据目录: /opt/pocketbase/pb_data - - 前端构建目录: /opt/pocketbase/pb_public -``` - -立即访问 `https://your-domain.com` 查看网站，访问 `https://your-domain.com/_/` 进入后台管理。 - ---- - -## 🪟 方式二：Windows 部署 - -### 适用系统 - -- Windows 10/11 (专业版/企业版) -- Windows Server 2019/2022 - -### 前置要求 - -```powershell -# 1. 以管理员身份打开 PowerShell -# 2. 启用脚本执行策略 -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - -# 3. 安装 Chocolatey (如果未安装) -Set-ExecutionPolicy Bypass -Scope Process -Force -[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 -iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) -refreshenv -``` - -### 运行安装脚本 - -```powershell -# 1. 克隆仓库 -git clone https://git.grxiao.cn/yuns/plerr-open.git -cd plerr-open - -# 2. 运行安装脚本 (管理员 PowerShell) -.\scripts\install.ps1 - -# 或传参 -.\scripts\install.ps1 -Domain "your-domain.com" -Email "admin@your-domain.com" -``` - -### Windows 特有说明 - -| 组件 | 说明 | -|------|------| -| PocketBase | 通过 NSSM 作为 Windows 服务运行 | -| Nginx | 通过 NSSM 作为 Windows 服务运行 | -| SSL 证书 | 使用 Certbot (Chocolatey 安装) | -| 定时任务 | 使用 Windows 任务计划程序 | -| 日志查看 | `C:\pocketbase\logs\` | - ---- - -## 🐳 方式三：Docker 容器化部署 - -### 前置要求 - -```bash -# 安装 Docker & Docker Compose -curl -fsSL https://get.docker.com | bash -systemctl enable docker --now - -# 安装 Docker Compose v2 -docker compose version -``` - -### 快速启动 - -```bash -# 1. 进入 docker 目录 -cd docker - -# 2. 复制环境变量模板 -cp .env.example .env - -# 3. 编辑配置 -vim .env -``` - -**`.env` 关键配置：** - -```env -# 域名配置 -DOMAIN=your-domain.com -EMAIL=admin@your-domain.com - -# PocketBase 配置 -PB_ENCRYPTION_KEY=your-32-char-base64-key -PB_ADMIN_EMAIL=admin@yunsheng.digital -PB_ADMIN_PASSWORD=YourStrongPassword123! - -# 时区 -TZ=Asia/Shanghai -``` - -### 生成加密密钥 - -```bash -# 生成 32 字节 Base64 密钥 -openssl rand -base64 32 -``` - -### 启动服务 - -```bash -# 构建并启动 -docker compose up -d --build - -# 查看日志 -docker compose logs -f - -# 查看状态 -docker compose ps -``` - -### Docker Compose 服务说明 - -| 服务 | 端口 | 说明 | -|------|------|------| -| pocketbase | 8090 | 后端 API + Admin UI + 静态文件 | -| nginx | 80/443 | 反向代理 + SSL 终止 + 静态文件缓存 | -| certbot | - | 自动申请/续期 Let's Encrypt 证书 | - ---- - -## 🌐 域名与 SSL 配置 - -### 域名解析 - -在域名服务商控制台添加记录： - -| 记录类型 | 主机记录 | 记录值 | TTL | -|----------|----------|--------|-----| -| A | @ | 你的服务器公网 IP | 600 | -| A | www | 你的服务器公网 IP | 600 | - -> ⏳ 解析生效通常需要 1-10 分钟，可用 `dig your-domain.com` 验证 - -### SSL 证书 - -**自动模式（推荐）：** 一键脚本 / Docker 会自动申请 Let's Encrypt 证书并配置自动续期。 - -**手动申请：** - -```bash -# Linux (Certbot + Nginx) -sudo certbot --nginx -d your-domain.com -d www.your-domain.com - -# 仅申请证书 (不修改 Nginx 配置) -sudo certbot certonly --nginx -d your-domain.com -d www.your-domain.com - -# 测试自动续期 -sudo certbot renew --dry-run -``` - -**证书路径：** - -- Linux: `/etc/letsencrypt/live/your-domain.com/` -- Windows: `C:\Certbot\live\your-domain.com\` -- Docker: `/etc/letsencrypt/live/your-domain.com/` (容器内) - ---- - -## 🔧 后台初始化 - -### 首次登录 - -1. 访问 `https://your-domain.com/_/` -2. 使用默认账号登录： - - **邮箱**: `admin@yunsheng.digital` - - **密码**: `YunSheng@2024!Admin` - -### 必做安全设置 - -⚠️ **请立即完成以下操作：** - -1. **修改管理员密码** - - 点击右上角头像 → Profile → Change Password - -2. **修改加密密钥备份** - - Linux: `cat /etc/systemd/system/pocketbase.service | grep PB_ENCRYPTION_KEY` - - 保存到安全位置（迁移服务器必需） - -3. **配置站点基本信息** - - Settings → Site Settings → 填写站点名称、描述、Logo、ICP 备案号等 - -4. **启用背景音乐（可选）** - - Settings → Background Music → 上传音频文件或填写外链 - -5. **创建分类与标签** - - Collections → categories / tags → New Record - -6. **发布第一篇文章** - - Collections → posts → New Record → 使用 TipTap 编辑器撰写 - ---- - -## 🛠️ 常用维护命令 - -### Linux (systemd) - -```bash -# 服务管理 -systemctl status pocketbase # 查看状态 -systemctl restart pocketbase # 重启 -systemctl stop pocketbase # 停止 -systemctl start pocketbase # 启动 - -# Nginx -systemctl status nginx -systemctl reload nginx # 重载配置 (无中断) -nginx -t # 测试配置 - -# 查看日志 -journalctl -u pocketbase -f # 实时日志 -journalctl -u pocketbase -n 100 # 最近 100 行 -tail -f /var/log/nginx/access.log -tail -f /var/log/nginx/error.log - -# 备份 -/usr/local/bin/yunsheng-backup - -# 更新 -/usr/local/bin/yunsheng-update - -# 状态检查 -/usr/local/bin/yunsheng-status -``` - -### Windows (PowerShell) - -```powershell -# 服务管理 -net start PocketBase -net stop PocketBase -Restart-Service PocketBase - -net start nginx -net stop nginx - -# 查看日志 -Get-Content C:\pocketbase\logs\stdout.log -Wait -Get-Content C:\nginx\logs\error.log -Wait - -# 备份 -C:\pocketbase\scripts\backup.bat - -# 更新 -C:\pocketbase\scripts\update.bat - -# 状态 -C:\pocketbase\scripts\status.bat -``` - -### Docker - -```bash -# 服务管理 -docker compose ps -docker compose restart pocketbase -docker compose restart nginx - -# 查看日志 -docker compose logs -f pocketbase -docker compose logs -f nginx - -# 备份 (进入容器执行) -docker compose exec pocketbase pocketbase dump --dir=/pb_data --output=/backup/pb_$(date +%Y%m%d).zip - -# 更新镜像 -docker compose pull -docker compose up -d --build - -# 进入容器 -docker compose exec pocketbase sh -``` - ---- - -## 🔍 故障排查 - -### 1. 网站无法访问 (502 Bad Gateway) - -**原因**：PocketBase 服务未运行 - -```bash -# 检查服务状态 -systemctl status pocketbase - -# 查看错误日志 -journalctl -u pocketbase -n 50 - -# 常见解决： -# - 端口 8090 被占用: ss -tlnp | grep 8090 -# - 权限问题: chown -R www-data:www-data /opt/pocketbase -# - 加密密钥错误: 检查 systemd 服务文件中的 PB_ENCRYPTION_KEY -``` - -### 2. 静态资源 404 (CSS/JS/图片加载失败) - -**原因**：前端构建产物未部署或 Nginx root 路径错误 - -```bash -# 检查构建产物 -ls -la /opt/pocketbase/pb_public/ - -# 应该看到 index.html、assets/ 目录 -# 如果为空，重新构建前端： -cd /path/to/project/apps/web -pnpm build -cp -r dist/* /opt/pocketbase/pb_public/ - -# 检查 Nginx 配置 root 路径 -grep -n "root" /etc/nginx/sites-enabled/yunsheng-digital -``` - -### 3. SSL 证书申请失败 - -```bash -# 检查域名解析 -dig your-domain.com +short -# 必须返回服务器公网 IP - -# 检查 80 端口可达性 -curl -I http://your-domain.com/.well-known/acme-challenge/test - -# 手动申请 (调试模式) -certbot certonly --nginx -d your-domain.com -v --dry-run -``` - -### 4. 文件上传失败 / 体积过大 - -**修改上传限制：** - -```bash -# 1. PocketBase 启动参数 (systemd 服务文件) -ExecStart=... --maxUploadSize=104857600 # 100MB - -# 2. Nginx 配置 -client_max_body_size 100M; - -# 3. 重启生效 -systemctl daemon-reload -systemctl restart pocketbase nginx -``` - -### 5. 数据库损坏 / 锁定 - -```bash -# 停止服务 -systemctl stop pocketbase - -# 备份当前数据 -cp -r /opt/pocketbase/pb_data /opt/pocketbase/pb_data.backup.$(date +%Y%m%d) - -# 尝试修复 (PocketBase 内置) -/opt/pocketbase/pocketbase migrate --dir=/opt/pocketbase/pb_data --migrationsDir=/opt/pocketbase/pb_migrations - -# 或从备份恢复 -/opt/pocketbase/pocketbase restore --dir=/opt/pocketbase/pb_data --input=/backup/pb_backup.zip - -# 重启 -systemctl start pocketbase -``` - -### 6. 内存不足 (OOM Killer) - -```bash -# 检查内存 -free -h - -# 添加 Swap (临时缓解) -fallocate -l 2G /swapfile -chmod 600 /swapfile -mkswap /swapfile -swapon /swapfile -echo '/swapfile none swap sw 0 0' >> /etc/fstab - -# 限制 PocketBase 内存 (systemd) -MemoryLimit=512M -``` - ---- - -## ⚙️ 进阶配置 - -### 1. 配置 CDN (Cloudflare / 阿里云 CDN / 腾讯云 CDN) - -**优势**：隐藏源站 IP、DDoS 防护、静态资源加速 - -**关键设置**： - -``` -# Cloudflare 示例 -SSL/TLS 模式: Full (Strict) -开启: Automatic HTTPS Rewrites, Always Use HTTPS -缓存规则: - - 静态资源 (*.js, *.css, *.png, *.jpg 等) -> Cache Everything, Edge TTL: 1 年 - - HTML 页面 -> Bypass Cache (或短 TTL) - - /api/* -> Bypass Cache - - /_/ * -> Bypass Cache (Admin UI) -``` - -**Nginx 配合 CDN 获取真实 IP**： - -```nginx -# 在 http 块中添加 -set_real_ip_from 103.21.244.0/22; # Cloudflare IP 段 -set_real_ip_from 103.22.200.0/22; -# ... 更多 Cloudflare IP -real_ip_header CF-Connecting-IP; -``` - -### 2. 开启 HTTP/3 (QUIC) - -```nginx -# Nginx 1.25+ 支持 -server { - listen 443 quic reuseport; - listen 443 ssl http2; - # ... -} -``` - -### 3. 配置对象存储 (S3 兼容) 存储上传文件 - -**PocketBase 支持 S3 存储后端**： - -```bash -# 启动参数添加 ---s3Endpoint=https://s3.your-provider.com \ ---s3Bucket=your-bucket \ ---s3AccessKey=YOUR_ACCESS_KEY \ ---s3SecretKey=YOUR_SECRET_KEY \ ---s3Region=auto -``` - -### 4. 迁移到 PostgreSQL (高并发场景) - -PocketBase v0.22+ 实验性支持 PostgreSQL： - -```bash -# 启动参数 ---dsn="postgres://user:pass@host:5432/dbname?sslmode=require" -``` - -> ⚠️ 迁移需谨慎，建议先测试环境验证 - -### 5. 多服务器负载均衡 - -``` - ┌─────────────┐ - 用户 ───→ CDN/WAF ───→ Nginx (LB) ───→ PocketBase #1 - │ └─────────────┘ - │ ┌─────────────┐ - └──────────────→ PocketBase #2 - └─────────────┘ -``` - -**注意**： -- PocketBase 需要共享同一数据库 (PostgreSQL) -- 实时订阅 需要 Redis 适配器 (开发中) -- 静态文件需共享存储 (NFS/S3) - ---- - -## 📦 更新日志 - -| 版本 | 日期 | 说明 | -|------|------|------| -| v1.0.0 | 2024-01-15 | 初始版本发布 | - ---- - -## 🤝 获取帮助 - -- **GitHub Issues**: [提交问题](https://git.grxiao.cn/yuns/plerr-open/issues) -- **文档中心**: [docs.yunsheng.digital](https://docs.yunsheng.digital) -- **邮件支持**: tech@yunsheng.digital - ---- - -## 📄 许可证 - -MIT License - 详见 [LICENSE](../LICENSE) - ---- - -> 💡 **提示**：部署遇到问题？请先查看 [故障排查](#故障排查) 章节，大多数问题都能自行解决。如果仍无法解决，请提供完整的错误日志和服务器环境信息提交 Issue。 \ No newline at end of file