plerr-open/docs/DEPLOY.md

云升数码 - 部署教程

一文搞定从零到线上的完整部署流程，支持 Linux / Windows / Docker 三种方式

---

📋 目录

• 准备工作
• 方式一：Linux 一键部署（推荐）
• 方式二：Windows 部署
• 方式三：Docker 容器化部署
• 域名与 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：连接服务器

# 使用 SSH 连接（替换为你的服务器 IP）
ssh root@your-server-ip

# 或使用密钥登录
ssh -i ~/.ssh/id_rsa root@your-server-ip

步骤 2：下载并运行安装脚本

# 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：按提示输入信息

脚本会交互式询问：

请输入域名 (例: yunsheng.digital): your-domain.com
请输入邮箱 (用于 SSL 证书): admin@your-domain.com

💡 提示：如果不想交互，可直接传参：

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：访问验证

部署成功后会显示：

==========================================
  部署完成！
==========================================

📋 重要信息：
  - 网站地址: 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

前置要求

# 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

运行安装脚本

# 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 容器化部署

前置要求

# 安装 Docker & Docker Compose
curl -fsSL https://get.docker.com | bash
systemctl enable docker --now

# 安装 Docker Compose v2
docker compose version

快速启动

# 1. 进入 docker 目录
cd docker

# 2. 复制环境变量模板
cp .env.example .env

# 3. 编辑配置
vim .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

生成加密密钥

# 生成 32 字节 Base64 密钥
openssl rand -base64 32

启动服务

# 构建并启动
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 证书并配置自动续期。

手动申请：

# 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)

# 服务管理
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)

# 服务管理
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

# 服务管理
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 服务未运行

# 检查服务状态
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 路径错误

# 检查构建产物
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 证书申请失败

# 检查域名解析
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. 文件上传失败 / 体积过大

修改上传限制：

# 1. PocketBase 启动参数 (systemd 服务文件)
ExecStart=... --maxUploadSize=104857600  # 100MB

# 2. Nginx 配置
client_max_body_size 100M;

# 3. 重启生效
systemctl daemon-reload
systemctl restart pocketbase nginx

5. 数据库损坏 / 锁定

# 停止服务
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)

# 检查内存
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：

# 在 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 1.25+ 支持
server {
    listen 443 quic reuseport;
    listen 443 ssl http2;
    # ...
}

3. 配置对象存储 (S3 兼容) 存储上传文件

PocketBase 支持 S3 存储后端：

# 启动参数添加
--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：

# 启动参数
--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: 提交问题
• 文档中心: docs.yunsheng.digital
• 邮件支持: tech@yunsheng.digital

---

📄 许可证

MIT License - 详见 LICENSE

---

💡 提示：部署遇到问题？请先查看 故障排查 章节，大多数问题都能自行解决。如果仍无法解决，请提供完整的错误日志和服务器环境信息提交 Issue。