# 云升数码 - 部署教程

> 一文搞定从零到线上的完整部署流程，支持 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。