606 lines
14 KiB
Markdown
606 lines
14 KiB
Markdown
# 云升数码 - 部署教程
|
||
|
||
> 一文搞定从零到线上的完整部署流程，支持 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。
|