# 启优学学习资讯后台

项目采用与官网同端口的 Astro 内容后台：Markdown 文件负责存储，Astro 同时提供管理 API 与静态页面生成。文章列表、分类页和详情页均预渲染为 HTML，便于 SEO 与 AI 搜索发现。

## 本地使用

```bash
source ~/.nvm/nvm.sh
nvm use 20
cp .env.example .env
npm install
npm run build
npm start
```

- 官网：`http://localhost:8793/`
- 后台：`http://localhost:8793/admin/`
- 学习资讯：`http://localhost:8793/articles/`

## 环境变量

- `CMS_PORT`：官网与后台共用端口，默认 `8793`
- `CMS_PASSWORD`：后台初始/主密码
- `CMS_SECRET`：会话签名密钥
- `CMS_API_KEY`：Bearer API 密钥
- `CMS_DATA_DIR`：文章、分类与上传文件的持久化目录
- `CMS_BUILD_LOCK`：发布重建共享锁

生产示例：

```dotenv
CMS_PORT=8793
CMS_DATA_DIR=/root/qiyouxue/shared/cms-data
CMS_BUILD_LOCK=/root/qiyouxue/shared/site-build.lock
```

## 内容工作流

- 工作稿：`src/content/articles/`
- 已发布：`src/content/published/`
- 默认分类：学情指南、学习方法、家长课堂、服务说明
- 支持新建、编辑、发布、下架、删除与未发布修改回退
- 支持分类新增、重命名、删除与文章迁移
- 支持 Markdown、Word `.docx` 导入和内嵌图片提取
- 支持图片上传、Markdown 预览和后台密码修改

生产环境配置 `CMS_DATA_DIR` 后，内容持久化到仓库外，不随单目录部署被覆盖。发布、下架、删除与分类变更会触发共享锁保护的原子站点重建。

## API

后台浏览器会话与 Bearer API 均由 `/api/cms/*` 提供。API 调用使用：

```http
Authorization: Bearer <CMS_API_KEY>
```

Word 导入示例字段：

```json
{
  "fileName": "学习方法文章.docx",
  "category": "学习方法",
  "dataUrl": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,..."
}
```

## 部署

`.gitlab-ci.yml` 使用单目录覆盖部署：停止 `qiyouxue` PM2 进程，更新 `/root/qiyouxue/current`，关联 `/root/qiyouxue/shared/.env`，安装依赖并构建，重新启动、健康检查，然后安装并验证 Nginx 配置。

- 部署根目录：`/root/qiyouxue`
- PM2 应用名：`qiyouxue`
- 服务端口：`8793`
- Nginx 配置：`/etc/nginx/conf.d/qiyouxue.conf`
- 公网域名：`qiyouxueedu.com`

Runner 需具备安装固定 Nginx 配置、执行 `nginx -t` 与 reload 的最小 sudo 权限。生产密钥、上传文件、CMS 数据与构建锁必须位于 `shared/`。
