# 云枢社区完整部署教程

本文适用于全新服务器部署和已有站点升级。示例域名使用 `community.example.com`，实际使用时请全部替换为你的域名。

## 一、部署结构

```text
浏览器 / 安卓 App / H5 / 小程序 / 机器人
                    │
                    ▼
             HTTPS 反向代理
           Nginx / Apache
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
     admin-ui-v2/*          api/*.php
   三套管理后台界面         社区业务 API
          │                   │
          └─────────┬─────────┘
                    ▼
             PHP 7.4+ / PHP-FPM
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
       MySQL 5.7+         uploads/ 本地文件
```

整个后端目录就是网站根目录。不要把网站根目录设置为 `api/`、`admin/` 或 `admin-ui-v2/`。

## 二、服务器要求

| 项目 | 最低要求 | 推荐 |
| --- | --- | --- |
| 操作系统 | 64 位 Linux | Ubuntu 22.04 / Rocky Linux 9 |
| CPU | 1 核 | 2 核及以上 |
| 内存 | 2 GB | 4 GB 及以上 |
| 磁盘 | 10 GB 可用 | 40 GB 及以上 |
| Web 服务 | Nginx 1.18+ | Nginx + PHP-FPM |
| PHP | PHP 7.4+ | PHP 8.1 或 8.2 |
| MySQL | MySQL 5.7+ / MariaDB 10.3+ | MySQL 8.0 |
| 字符集 | utf8mb4 | utf8mb4_unicode_ci |

### PHP 扩展

必需：

```text
pdo_mysql
mbstring
json
session
```

推荐：

```text
curl
zip
openssl
fileinfo
gd
```

宝塔面板可在“软件商店 → PHP 版本 → 设置 → 安装扩展”中安装。安装完成后重启对应 PHP-FPM。

检查 PHP：

```bash
php -v
php -m | grep -E 'pdo_mysql|mbstring|curl|zip|openssl|fileinfo|gd'
php -r 'var_dump(class_exists("ZipArchive"));'
```

`class_exists("ZipArchive")` 应返回 `true`，否则在线系统更新不可用。

## 三、解析域名和创建站点

1. 在域名服务商添加 A 记录：

```text
community.example.com → 服务器公网 IP
```

2. 在宝塔面板创建 PHP 站点。
3. PHP 版本选择 8.1 或 8.2。
4. 网站根目录指向后端项目的实际根目录。
5. 申请 SSL 证书并强制 HTTPS。

网站根目录必须直接包含：

```text
admin/
admin-ui/
admin-ui-v2/
api/
installer/
index.php
install.php
```

错误示例：

```text
/www/wwwroot/community/云枢社区后端/api/
```

这样会导致安装入口、后台和 API 路径全部错误。

## 四、上传项目与设置权限

Linux 示例：

```bash
chown -R www:www /www/wwwroot/community
find /www/wwwroot/community -type d -exec chmod 755 {} \;
find /www/wwwroot/community -type f -exec chmod 644 {} \;
chmod -R 775 /www/wwwroot/community/uploads
```

宝塔 PHP-FPM 通常使用 `www` 用户。如果实际运行用户不同，请替换为实际用户。

首次安装前：

- `api/config.local.php` 可以不存在，安装器会生成。
- `api/install.lock.php` 不应存在。
- `api/license_config.php` 必须在安装和授权接入前准备好。
- 不要让浏览器直接访问配置文件。

## 五、创建 MySQL 数据库

在宝塔“数据库”中创建数据库：

```text
数据库名：community
用户名：community_user
密码：使用强密码
字符集：utf8mb4
```

记录数据库名、用户名和密码，在安装向导中填写。

已有站点升级前，必须先完整备份数据库：

```bash
mysqldump -u root -p --single-transaction --routines --triggers community > community-backup.sql
```

备份文件不要保存在网站根目录。

## 六、运行安装向导

访问：

```text
https://community.example.com/install.php
```

安装步骤：

1. 检查 PHP 版本和扩展。
2. 检查目录写入能力。
3. 填写数据库连接。
4. 选择是否保留已有数据库内容。
5. 创建管理员账号。
6. 执行建表和初始化。
7. 生成 `api/config.local.php` 与 `api/install.lock.php`。

安装完成后再次访问 `install.php` 应被安装锁阻止。

## 七、HTTPS 与 Web 安全

Nginx 建议禁止直接下载：

```nginx
location ~* \.(sql|zip|log|bak|ini)$ {
    deny all;
}

location ~ ^/api/(config\.local\.php|install\.lock\.php|license_config\.php)$ {
    deny all;
}
```

系统更新存储目录不得公开：

```nginx
location ^~ /storage/ {
    deny all;
}
```

同时建议：

- 后台域名限制管理员 IP。
- 管理后台启用强密码和访问密钥。
- 不在 `uploads/`、`api/` 中保存 SQL 备份。
- 关闭 PHP 错误页面公开展示，错误写入服务端日志。
- 定期更新 PHP、Nginx 和 MySQL。

完整 Nginx 参考见 `nginx.conf.example`。

## 八、购买并配置域名授权

1. 打开授权平台并注册账号。
2. 选择“购买授权”。
3. 选择“云枢社区”程序。
4. 填写不带协议和路径的域名：

```text
community.example.com
```

5. 选择月卡、季卡、半年卡、年卡或永久授权。
6. 完成支付后确认授权状态和到期时间。

服务端编辑：

```text
api/license_config.php
```

示例：

```php
<?php
return [
    'enabled' => true,
    'server_url' => 'https://auth.example.com/auth_server.php',
    'app_key' => '授权平台中云枢社区程序的 AppKey',
    'timeout' => 6,
    'cache_minutes' => 5,
];
```

该文件不要公开，也不要在系统设置中重复配置。

## 九、管理后台入口

```text
经典后台：https://community.example.com/admin/
原版 SPA：https://community.example.com/admin-ui/
星云动效版：https://community.example.com/admin-ui-v2/
数据大屏：https://community.example.com/admin-ui-v2/big-screen.html
```

上线前建议配置：

- 站点名称、Logo、SEO、ICP 备案号。
- 管理员密码、后台访问密钥。
- SMTP 邮件和工单提醒开关。
- 板块、审核规则、举报处理流程。
- AppKey 与 API 对接测试。
- 维护模式、备份计划和系统更新。

## 十、系统更新

授权管理后台“系统设置 → 系统更新发布”：

1. 选择云枢社区程序。
2. 填写版本号、版本编码、发布日期。
3. 填写更新标题和更新日志。
4. 粘贴 ZIP 下载链接。
5. 授权服务器自动下载包、计算 SHA-256 并发布。

社区后台：

```text
系统配置 → 系统更新
```

检查更新后，输入 `APPLY` 执行在线升级。系统会：

- 校验授权域名和 AppKey。
- 校验 ZIP 和 SHA-256。
- 备份被覆盖的文件。
- 解压覆盖社区根目录。
- 写入新版本号。
- 保留回滚记录。

更新包不能覆盖：

```text
api/config.local.php
api/license_config.php
api/install.lock.php
config/
uploads/
storage/
releases/
```

## 十一、备份策略

建议：

- 每天备份 MySQL。
- 每周备份 `uploads/`。
- 更新前创建完整站点与数据库备份。
- 至少保留 7 天备份。
- 将备份复制到另一台服务器或对象存储。

在线更新的回滚目录位于 PHP 系统临时目录，服务器重启或临时文件清理后可能消失，不能代替正式备份。

## 十二、常见故障

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 数据库连接失败 | 数据库账号、库名、端口错误 | 核对宝塔数据库配置并重新安装 |
| 后台空白 / 500 | PHP 扩展、权限或错误 | 查看 PHP-FPM 与站点错误日志 |
| 图片上传失败 | 上传限制或目录不可写 | 调整 uploads 权限与 upload_max_filesize |
| 当前程序未授权 | 域名、AppKey、到期时间异常 | 核对授权平台与 license_config.php |
| ZIP 扩展缺失 | 站点 PHP 未加载 zip | 给实际 PHP 版本安装 zip 并重启 |
| 更新下载失败 | 授权服务器或下载链接不可访问 | 检查 HTTPS、防火墙和下载令牌 |
| 经典后台样式缺失 | CDN 无法访问 | 优先使用动效版或本地化静态资源 |

任何 500 错误都应先查：

```text
PHP-FPM 日志
Nginx error.log
站点 PHP 错误日志
```

## 十三、部署检查清单

- [ ] 域名已解析并启用 HTTPS
- [ ] PHP 版本和扩展符合要求
- [ ] MySQL 字符集为 utf8mb4
- [ ] 网站根目录结构正确
- [ ] uploads 与临时目录可写
- [ ] 安装锁已生成
- [ ] 授权域名、AppKey 和到期时间正常
- [ ] SMTP 邮件可正常发送
- [ ] AppKey 和接口测试通过
- [ ] 数据库与 uploads 备份正常
- [ ] 后台管理员密码已加强

## 相关文档

安卓项目社区搭建教程仅向已购买有效授权的用户开放。登录授权用户中心后，打开“服务支持 → 部署文档”查看和下载。