CMS

一个基于配置驱动的轻量级 CMS 项目，包含管理端前端、Beego 后端 API、MySQL 存储和 OSS 文件上传能力。

详细设计文档见 docs/architecture.md。

项目概览

该项目用于维护三层内容结构：

• Business：业务项/主题域
• Theme：业务项下的一类主题模板，使用 schema_json 定义内容结构
• ThemeItem：主题模板下的具体内容项，使用 content_json 保存实际内容

项目当前包含两类接口：

• 管理端接口：/admin/*，用于业务项、主题模板、内容项和文件上传管理
• 公共接口：/api/public/*，用于按已上线状态读取主题和内容

技术栈

• 前端：Vue 3、Vite
• 后端：Go 1.25、Beego v2
• 数据库：MySQL
• 文件存储：阿里云 OSS
• 测试：
  • 后端：Go testing + httptest
  • 前端：Node 原生 assert 风格的 .mjs 测试脚本

目录结构

cms/
├─ api/                    # Go 后端
│  ├─ conf/                # Beego 配置示例
│  ├─ controllers/         # HTTP 控制器
│  ├─ database/            # SQL 建表脚本
│  ├─ models/              # 领域模型
│  ├─ routers/             # 路由注册与依赖初始化
│  ├─ services/schema/     # schema/content 校验
│  ├─ storage/             # MySQL 仓储与 OSS 上传实现
│  ├─ tests/               # 接口级测试
│  └─ main.go              # 服务入口
├─ web/                    # Vue 管理端
│  ├─ src/api/             # 前端 API 封装
│  ├─ src/components/      # 表单、JSON 编辑器等组件
│  ├─ src/pages/           # 业务项/主题/内容页面
│  ├─ src/utils/           # 视图状态与 schema 工具
│  └─ vite.config.js       # Vite 与代理配置
├─ docs/
│  └─ architecture.md      # 完整现状架构说明
└─ README.md

核心能力

• 业务项管理：创建、更新、列表查询
• 主题模板管理：创建、更新、按业务项查询
• 配置驱动内容建模：使用 schema_json 描述动态表单结构
• 内容项管理：根据主题模板 schema 录入和维护 content_json
• 文件上传：通过 /admin/upload 上传到 OSS，并把返回 URL 写入内容 JSON
• 公共读取：仅暴露已上线主题和内容项

环境准备

建议环境：

• Go 1.25
• Node.js 20.19+ 或 22.12+
• MySQL 8.x

后端启动

1. 创建数据库：

create database if not exists cms default charset utf8mb4 collate utf8mb4_unicode_ci;

2. 导入表结构：

mysql -uroot -p cms < api/database/schema.sql

3. 配置应用：

复制 api/conf/app.example.conf 为 api/conf/app.conf，至少补充 MySQL 配置。

示例：

appname = cms
httpport = 8080
runmode = dev
mysqldriver = mysql
mysqlhost = 127.0.0.1
mysqlport = 3306
mysqluser = root
mysqlpass = 
mysqldb = cms
ossendpoint =
ossbucket =
ossaccesskeyid =
ossaccesskeysecret =
ossdirectory = cms
osspublicbaseurl =

也可以通过环境变量覆盖完整 DSN：

$env:CMS_MYSQL_DSN="root:123456@tcp(127.0.0.1:3306)/cms?charset=utf8mb4&parseTime=false&loc=Local"

4. 如需上传文件，继续配置 OSS：

ossendpoint = https://oss-cn-shanghai.aliyuncs.com
ossbucket = your-bucket
ossaccesskeyid = your-access-key-id
ossaccesskeysecret = your-access-key-secret
ossdirectory = cms
osspublicbaseurl = https://your-bucket.oss-cn-shanghai.aliyuncs.com

5. 启动后端：

cd api
go run .

默认地址：

http://localhost:8080/

前端启动

安装依赖并启动：

cd web
npm install
npm run dev -- --host 127.0.0.1 --port 5173

默认地址：

http://127.0.0.1:5173/

Vite 已在 web/vite.config.js 中将 /admin 和 /api 代理到 http://localhost:8080。

测试

后端测试：

cd api
go test ./...

前端工具测试：

cd web
node src/utils/schemaForm.test.mjs
node src/utils/cmsView.test.mjs

接口概览

管理端接口：

• GET /admin/business
• POST /admin/business
• PUT /admin/business/:id
• GET /admin/business/:businessId/themes
• POST /admin/themes
• PUT /admin/themes/:id
• GET /admin/business/:businessId/themes/:themeId/items
• POST /admin/items
• GET /admin/items/:id
• PUT /admin/items/:id
• POST /admin/upload

公共接口：

• GET /api/public/business/:businessId/themes
• GET /api/public/business/:businessId/themes/:themeId/items

更完整的模块关系、数据流和架构图见 docs/architecture.md。