full/module/base/cms

CMS Content Management System

一个高性能、可扩展的内容管理系统微服务，基于 gRPC 和 HTTP Gateway 架构，提供文章管理、页面管理、分类管理、标签管理等核心内容管理功能。

🚀 特性

• 📝 文章管理: 完整的文章创建、编辑、删除、查询功能
• 📄 页面管理: 静态页面和动态页面管理
• 🏷️ 分类管理: 支持层级分类结构，灵活的内容组织
• 🔖 标签管理: 多标签系统，便于内容分类和检索
• 💬 评论系统: 完整的评论功能，支持嵌套评论
• 👍 互动功能: 点赞、踩赞、评论计数等社交功能
• 📎 附件管理: 文件附件上传和管理
• ⚡ 高性能: Redis缓存 + 数据库优化
• 🐳 容器化: 完整的Docker支持
• 📊 监控: 健康检查和APM集成
• 🔒 安全: 完善的错误处理和输入验证

📋 目录

• 快速开始
• 项目结构
• 核心功能
• API文档
• 开发指南
• 部署说明
• 性能优化
• 故障排除

🚀 快速开始

环境要求

• Go: 1.25.1+
• PostgreSQL: 12+
• Redis: 6+
• Docker: 20.10+ (可选)
• Protocol Buffers: 3.15+ (开发需要)

快速安装

# 克隆项目
git clone bsm/full/module/base/cms.git
cd cms

# 安装依赖
go mod download

# 生成代码
make proto

# 构建应用
make build

# 运行服务
make run

Docker 快速启动

# 启动完整服务栈
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f cms-service

📁 项目结构

cms/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 config/             # 配置管理
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 category/       # 分类相关逻辑
│   │   ├── 📁 pages/          # 页面相关逻辑
│   │   ├── 📁 post/           # 文章相关逻辑
│   │   └── 📁 tags/           # 标签相关逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol Buffers 生成代码
├── 📁 proto/                  # Protocol Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本和SQL文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
├── 🐳 Dockerfile              # Docker 镜像构建
├── 🐳 docker-compose.yml      # Docker 编排
├── 🔧 Makefile               # 构建脚本
└── 📖 README.md              # 项目文档

🔧 核心功能

1. 文章服务 (Post Service)

📝 文章管理

rpc Create(PostItem) returns (StatusReply)
rpc Modify(PostItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)

• 功能: 完整的文章CRUD操作
• 特性:
  • 支持富文本内容
  • 自动生成唯一键值
  • 支持分类和标签关联
  • 附件管理
  • 统计数据（点击量、点赞、评论等）

🔍 文章查询

rpc GetByIdentity(GetByIdentityRequest) returns (PostItem)
rpc GetByKey(GetByKeyRequest) returns (PostItem)
rpc Search(SearchRequest) returns (SearchReply)

• 功能: 多种方式查询文章
• 特性:
  • 按ID查询
  • 按键值查询
  • 关键词搜索
  • 分类筛选
  • 分页支持

💬 评论系统

rpc AddComment(CommentItem) returns (StatusReply)
rpc CommentList(CommentListRequest) returns (CommentListReply)
rpc ModifyComment(CommentItem) returns (StatusReply)
rpc DeleteComment(DeleteRequest) returns (StatusReply)

• 功能: 完整的评论管理
• 特性:
  • 嵌套评论支持
  • 评论计数
  • 评论点赞/踩赞

👍 互动功能

rpc IncrPostLike(IncrPostLikeRequest) returns (StatusReply)
rpc DescPostLike(DescPostLikeRequest) returns (StatusReply)
rpc IncrPostUnlike(IncrPostUnlikeRequest) returns (StatusReply)
rpc DescPostUnlike(DescPostUnlikeRequest) returns (StatusReply)

• 功能: 文章点赞/踩赞管理
• 特性: 实时计数更新

2. 分类服务 (Category Service)

🏷️ 分类管理

rpc Create(CategoryItem) returns (StatusReply)
rpc Modify(CategoryItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)

• 功能: 层级分类管理
• 特性:
  • 支持无限层级
  • 分类封面图片
  • 分类描述
  • 子分类预加载

3. 页面服务 (Pages Service)

📄 页面管理

rpc Create(PagesItem) returns (StatusReply)
rpc Modify(PagesItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
rpc GetByIdentity(GetByIdentityRequest) returns (PagesItem)
rpc GetByKey(GetByKeyRequest) returns (PagesItem)

• 功能: 静态页面和动态页面管理
• 特性:
  • 支持富文本内容
  • 标签关联
  • 附件管理
  • 多种查询方式

4. 标签服务 (Tags Service)

🔖 标签管理

rpc Create(TagsItem) returns (StatusReply)
rpc Modify(TagsItem) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)

• 功能: 标签系统管理
• 特性:
  • 标签颜色支持
  • 标签描述
  • 使用统计

📚 API文档

gRPC 服务

服务	方法	描述	端口
Post	Create	创建文章	12101
Post	Modify	修改文章	12101
Post	Delete	删除文章	12101
Post	Fetch	文章列表	12101
Post	GetByIdentity	按ID获取文章	12101
Post	GetByKey	按键值获取文章	12101
Post	Search	搜索文章	12101
Post	AddComment	添加评论	12101
Post	CommentList	评论列表	12101
Post	ModifyComment	修改评论	12101
Post	DeleteComment	删除评论	12101
Post	IncrPostLike	文章点赞	12101
Post	DescPostLike	取消文章点赞	12101
Post	IncrPostUnlike	文章踩赞	12101
Post	DescPostUnlike	取消文章踩赞	12101
Post	IncrCommentLike	评论点赞	12101
Post	DescCommentLike	取消评论点赞	12101
Post	IncrCommentUnlike	评论踩赞	12101
Post	DescCommentUnlike	取消评论踩赞	12101
Category	Create	创建分类	12101
Category	Modify	修改分类	12101
Category	Delete	删除分类	12101
Category	Fetch	分类列表	12101
Pages	Create	创建页面	12101
Pages	Modify	修改页面	12101
Pages	Delete	删除页面	12101
Pages	Fetch	页面列表	12101
Pages	GetByIdentity	按ID获取页面	12101
Pages	GetByKey	按键值获取页面	12101
Tags	Create	创建标签	12101
Tags	Modify	修改标签	12101
Tags	Delete	删除标签	12101
Tags	Fetch	标签列表	12101

HTTP Gateway

端点	方法	描述
/cms.Post/Create	POST	创建文章
/cms.Post/Modify	POST	修改文章
/cms.Post/Delete	POST	删除文章
/cms.Post/Fetch	POST	文章列表
/cms.Post/GetByIdentity	POST	按ID获取文章
/cms.Post/GetByKey	POST	按键值获取文章
/cms.Post/Search	POST	搜索文章
/cms.Category/Create	POST	创建分类
/cms.Category/Modify	POST	修改分类
/cms.Category/Delete	POST	删除分类
/cms.Category/Fetch	POST	分类列表
/cms.Pages/Create	POST	创建页面
/cms.Pages/Modify	POST	修改页面
/cms.Pages/Delete	POST	删除页面
/cms.Pages/Fetch	POST	页面列表
/cms.Pages/GetByIdentity	POST	按ID获取页面
/cms.Pages/GetByKey	POST	按键值获取页面
/cms.Tags/Create	POST	创建标签
/cms.Tags/Modify	POST	修改标签
/cms.Tags/Delete	POST	删除标签
/cms.Tags/Fetch	POST	标签列表

Swagger 文档

• 本地: http://localhost:12102/cms.swagger.json
• 在线: 通过 HTTP Gateway 访问完整的 API 文档

🛠️ 开发指南

开发环境设置

# 安装开发工具
make install-tools

# 设置Git钩子
git config core.hooksPath .githooks

# 启动开发模式
make dev

代码生成

# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger

测试

# 运行所有测试
make test

# 测试覆盖率
make test-coverage

# gRPC 功能测试
make test-grpc

# 代码检查
make lint

# 安全扫描
make security

数据库管理

# 初始化数据库
make init-db

# 备份数据库
make backup-db

🚀 部署说明

Docker 部署

# 构建镜像
make docker-build

# 启动服务栈
make docker-compose-up

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down

生产环境部署

1. 环境准备

   # 创建生产配置
   cp etc/cms_dev.yaml etc/cms_prod.yaml
   # 编辑生产配置...
   

2. 数据库初始化

   # 执行数据库迁移
   make migrate
   

3. 服务启动

   # 构建生产版本
   make build-linux
   
   # 启动服务
   ./build/cms-linux-amd64
   

Kubernetes 部署

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cms-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: cms-service
  template:
    metadata:
      labels:
        app: cms-service
    spec:
      containers:
      - name: cms-service
        image: cms:latest
        ports:
        - containerPort: 12101
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"

⚡ 性能优化

缓存策略

数据类型	缓存时间	策略
文章列表	10分钟	按分类+关键词缓存
文章详情	30分钟	按文章ID缓存
分类数据	1小时	全量缓存
标签数据	1小时	全量缓存
页面数据	1小时	按页面ID缓存

数据库优化

• 索引优化: 关键字段建立复合索引
• 查询优化: 使用预加载减少N+1查询
• 连接池: 配置合适的连接池大小
• 读写分离: 支持主从数据库配置

监控指标

# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics

🔧 配置说明

环境配置文件

# etc/cms_prod.yaml
Service: cms
Port: 12101

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=cms_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102

# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# APM监控
APM:
  Platform: elasticAPM
  Endpoint: http://apm-server:8200

环境变量

变量名	描述	默认值
SERVICE_ENV	运行环境	development
CONFIG_FILE	配置文件路径	etc/cms_dev.yaml
LOG_LEVEL	日志级别	info
TZ	时区设置	Asia/Shanghai

🐛 故障排除

常见问题

1. 服务启动失败

   # 检查端口占用
   netstat -tlnp | grep :12101
   
   # 检查配置文件
   make lint
   

2. 数据库连接失败

   # 测试数据库连接
   psql -h your-db-host -U postgres -d cms_db -c "SELECT 1;"
   

3. Redis连接失败

   # 测试Redis连接
   redis-cli -h your-redis-host ping
   

日志分析

# 查看服务日志
tail -f logs/cms.log

# 查看错误日志
grep ERROR logs/cms.log

# 查看性能日志
grep "slow query" logs/cms.log

性能调优

1. 内存优化

   # 监控内存使用
   go tool pprof http://localhost:6060/debug/pprof/heap
   

2. CPU优化

   # CPU性能分析
   go tool pprof http://localhost:6060/debug/pprof/profile
   

📊 数据模型

核心表结构

Cms_post - 文章表

CREATE TABLE Cms_post (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    key VARCHAR(255) UNIQUE NOT NULL,
    description VARCHAR(255) DEFAULT '',
    cover_path VARCHAR(255) DEFAULT '',
    author VARCHAR(255) DEFAULT '',
    author_identity VARCHAR(36) DEFAULT '',
    cms TEXT DEFAULT '',
    target_url VARCHAR(255) DEFAULT '',
    source_url VARCHAR(255) DEFAULT '',
    hits BIGINT DEFAULT 0,
    like_hits BIGINT DEFAULT 0,
    unlike_hits BIGINT DEFAULT 0,
    comment_hits BIGINT DEFAULT 0,
    has_accessory BOOLEAN DEFAULT false,
    type INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Cms_category - 分类表

CREATE TABLE Cms_category (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    category_key VARCHAR(255) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    cover_path VARCHAR(255) DEFAULT '',
    parent_id INTEGER DEFAULT 0,
    intro TEXT DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);

Cms_pages - 页面表

CREATE TABLE Cms_pages (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    key VARCHAR(255) UNIQUE NOT NULL,
    description VARCHAR(255) DEFAULT '',
    cover_path VARCHAR(255) DEFAULT '',
    cms TEXT DEFAULT '',
    has_accessory BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Cms_tags - 标签表

CREATE TABLE Cms_tags (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(255) NOT NULL,
    color VARCHAR(7) DEFAULT '#000000',
    intro TEXT DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Cms_comment - 评论表

CREATE TABLE Cms_comment (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(36) UNIQUE NOT NULL,
    post_identity VARCHAR(36) NOT NULL,
    parent_id INTEGER DEFAULT 0,
    author VARCHAR(255) DEFAULT '',
    author_identity VARCHAR(36) DEFAULT '',
    content TEXT NOT NULL,
    like_hits BIGINT DEFAULT 0,
    unlike_hits BIGINT DEFAULT 0,
    comment_hits BIGINT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🤝 贡献指南

开发流程

1. Fork 项目
2. 创建特性分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 创建 Pull Request

代码规范

• 遵循 Go 官方代码规范
• 使用 gofmt 格式化代码
• 添加必要的注释和文档
• 编写单元测试

提交规范

type(scope): description

[optional body]

[optional footer]

类型:

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• test: 测试
• chore: 构建过程或辅助工具的变动

📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

👥 团队

• 作者: David Yan (david.yan@qq.com)
• 维护者: BSM 开发团队
• 项目地址: bsm/full/module/base/cms

🔗 相关链接

• BSM SDK
• API 文档
• 问题反馈

---

⭐ 如果这个项目对你有帮助，请给它一个星标！

Made with ❤️ by BSM Team