VitPress-CMS/README.md

VitePress-CMS

VitePress-CMS 是一个面向 VitePress 的可视化内容管理后台。它的目标是让用户通过网页界面管理 Markdown 页面、站点结构、主题配置与 GitHub 发布流程。

当前版本

当前项目已经从静态原型升级为 Vue 3 + TypeScript + Vite 工程。

已完成的原型能力：

• 页面目录、搜索与新建页面
• Markdown 编辑与预览切换
• Frontmatter 标题和描述编辑
• 导航栏与侧边栏管理界面
• 站点基础配置界面
• 发布中心与部署状态模拟

本地运行

npm install
npm run dev

Windows PowerShell 如果拦截 npm.ps1，可以使用：

npm.cmd install
npm.cmd run dev

初始账户

项目启动时会自动创建 SQLite 数据库：

data/vitepress-cms.sqlite

如果数据库里还没有系统管理员，会自动创建初始账户：

邮箱：admin@example.com
密码：admin123456
角色：system_admin

可以通过环境变量修改初始账户：

CMS_ADMIN_EMAIL=admin@your-domain.com
CMS_ADMIN_PASSWORD=change-me

构建验证

npm run build

测试站点

VitePress 测试站点放在项目内的独立子目录：

test-vitepress/

它有自己的 package.json 和依赖，不会让 VitePress 成为 CMS 主项目的一部分。这样既方便开发测试，也能保持主项目依赖干净。

运行测试站点：

cd test-vitepress
npm install
npm run dev

GitHub 连接

当前版本支持两种 GitHub 连接方式：

1. GitHub OAuth 登录后选择仓库。
2. 手动输入 token、owner、repo、branch 和站点目录。

使用 OAuth 登录前，需要创建 GitHub OAuth App，并配置环境变量：

GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx

开发环境 callback URL：

http://localhost:5173/api/github/callback

Token 或 OAuth 授权至少需要仓库内容读写权限。保存页面或配置时，CMS 会通过 GitHub Contents API 创建 commit。

站点目录示例：

• VitePress 在仓库根目录：留空
• VitePress 在 docs/：填写 docs

下一步

1. 建立 GitHub OAuth 登录流程。
2. 读取仓库中的 docs/ 页面文件。
3. 解析 .vitepress/config.ts 中的常用配置。
4. 将页面和配置修改提交为 GitHub commit。
5. 显示 GitHub Pages 或 Actions 部署状态。