# VSCMS 部署文档（宝塔环境）

## 一、服务器要求

| 项 | 要求 |
| --- | --- |
| 系统 | Ubuntu / CentOS（本产品线统一宝塔面板） |
| PHP | >= 8.1（推荐 8.3），扩展：pdo_mysql / mbstring / openssl / gd / zip / bcmath / fileinfo / curl |
| MySQL | 8.x，utf8mb4 |
| Web | Nginx（宝塔） |
| Redis | 可选（缓存/队列） |
| 磁盘 | 建议 40G+（发布产物与媒体库） |
| 网络 | 域名解析到本机；需可访问 api.deepseek.com（官方网关模式则仅需访问官方总控） |

## 二、部署步骤

1. **创建站点**（宝塔）：域名 / 根目录，PHP 8.3，站点根目录临时保持默认即可（后面改为 `server/public`）
2. **上传代码**至站点目录（或 git clone），建库并授权
3. **配置 `server/.env`**（参考 `.example.env`）：
   ```
   DB_NAME / DB_USER / DB_PASS / DB_PREFIX = cms_
   JWT_SECRET / DATA_KEY（64位随机十六进制）
   # 离线直连 AI 时（可选，推荐用官方网关）：
   AI_BASE_URL = https://api.deepseek.com
   AI_MODEL = deepseek-flash
   AI_API_KEY = sk-xxxx
   ```
4. **初始化**：
   ```bash
   cd server && php think cms:migrate && php think cms:seed
   ```
   也可访问 `/install/` 安装向导（安装完成后系统生成 `storage/install.lock`）
5. **切换站点根目录**为 `server/public`，配置 Nginx（参考 `deploy/nginx.example.conf`）
6. **一键配置**（root）：
   ```bash
   bash deploy/install.sh /www/wwwroot/你的站点目录
   ```
   脚本完成：发布目录与权限、Nginx publish.d 引入、sudo 白名单（重载 Nginx + acme.sh）、心跳计划任务
7. **构建管理端前端**（开发机或服务器）：
   ```bash
   cd admin && npm install && npm run build   # 产物输出 server/public/admin
   ```
8. 访问 `/admin/` 登录，立即修改默认账号密码

## 三、发布与域名绑定

- 站点管理 → 编辑站点填写「绑定域名」→ 发布 → 发布弹窗点「绑定域名」
- 系统自动：写 Nginx 配置（`/www/server/nginx/conf/publish.d/`）→ 申请 Let's Encrypt 证书（acme.sh）→ 开启 HTTPS
- 发布产物：`server/publish/{站点ID}/releases/{版本}`，`current` 软链指向线上版本

## 四、升级流程

```bash
cd /www/wwwroot/你的站点目录
git pull
cd server && php think cms:migrate && php think cms:seed
cd ../admin && npm run build
chown -R www:www ../server/runtime ../server/storage ../server/public/admin
```

## 五、计划任务

| 任务 | 频率 | 命令 |
| --- | --- | --- |
| 官方心跳 | 每 6 小时 | `php think cms:heartbeat` |
| 数据库/附件备份 | 每日 | 参考 `deploy/backup.sh`（如需要可移植 OA 备份脚本） |

## 六、常见问题

- **刷新后台 404**：确认 Nginx 的 `/admin/` 有 `try_files ... /admin/index.html` 回退（`deploy/nginx.example.conf`）
- **绑定域名失败**：确认 `deploy/install.sh` 已执行（sudo 白名单与 publish.d 引入）；查看 `/www/wwwlogs/` 下 Nginx 错误日志
- **AI 报错“未配置”**：配置 `.env` 的 `AI_API_KEY`，或在「系统信息与授权」中接入官方总控并激活
- **上传的图片 404**：确认站点已发布（图片随发布拷贝到发布目录）或访问的是预览域名
- **重装系统**：删除 `server/storage/install.lock` 并临时放开 `/install/` 访问限制