Cosmos Blog

一个全栈个人博客系统，采用 React + Tailwind CSS 前端、Rust + Axum 后端、PostgreSQL 数据库，支持 k3s/Kubernetes 部署。

特性

• 🌌 星空暗色主题 + 杂志风排版
• 📝 CodeMirror 6 Markdown 编辑器，支持编辑/分屏/预览三种模式
• 💾 编辑器实时保存草稿
• 🔐 GitHub OAuth 登录，三层权限（guest / user / admin）
• 💬 评论系统
• 🏷️ 标签云与搜索
• 📡 RSS 订阅
• 🐳 Docker / Docker Compose 一键运行
• ☸️ k3s + Traefik Ingress 部署配置

技术栈

后端

• Axum + Tokio
• sqlx（PostgreSQL）
• pulldown-cmark 渲染 Markdown
• jsonwebtoken 签发 JWT
• GitHub OAuth

前端

• React 19 + TypeScript + Vite
• Tailwind CSS + @tailwindcss/typography
• CodeMirror 6 Markdown 编辑器
• Framer Motion 动画
• TanStack Query 数据获取
• Zustand 状态管理

目录结构

.
├── backend/              # Rust + Axum 后端
│   ├── src/
│   ├── migrations/       # sqlx 数据库迁移
│   └── Dockerfile
├── frontend/             # React + Tailwind 前端
│   ├── src/
│   ├── Dockerfile
│   └── nginx.conf
├── k8s/                  # Kubernetes manifests
│   ├── postgres/         # PostgreSQL StatefulSet
│   ├── backend/          # 后端 Deployment
│   ├── frontend/         # 前端 Deployment
│   ├── ingress.yaml      # Traefik Ingress
│   └── kustomization.yaml
├── docker-compose.yml
└── .env.example

快速开始

1. 准备环境变量

cp .env.example .env
# 编辑 .env，填入 GitHub OAuth 参数和你的 GitHub 用户 ID

2. Docker Compose 一键启动

docker compose up --build

访问：http://localhost

后端 API：http://localhost:3000/api/health

3. 本地开发

启动 PostgreSQL：

docker compose up postgres -d

启动后端：

cd backend
cargo run

启动前端：

cd frontend
npm install
npm run dev

权限模型

角色	权限
guest	浏览公开文章、评论、标签、RSS
user	guest 权限 + 发表评论
admin	user 权限 + 文章 CRUD、发布/私有、删除任意评论

管理员通过 GITHUB_ADMIN_ID 环境变量指定，首次 GitHub 登录时自动赋予 admin 角色。

编辑器工作流

1. 管理员在 /admin 点击"新建文章"。
2. 编辑器默认分屏模式：左侧 CodeMirror 编辑 Markdown，右侧实时预览。
3. 输入停止 2 秒后自动保存草稿到后端 drafts 表。
4. 点击"发布"：将草稿渲染为 HTML，状态变为 public。
5. 已发布文章可转为 private（私有）或重新编辑。

API 概览

公开接口

方法	路径	说明
GET	/api/health	健康检查
GET	/api/posts?page=&tag=&q=	公开文章列表
GET	/api/posts/:slug	文章详情
GET	/api/posts/:slug/comments	文章评论列表
GET	/api/tags	标签云
GET	/api/rss.xml	RSS Feed

认证 / 用户 / 管理员接口

详见 backend/README.md。

部署到 k3s

1. 构建并推送镜像

docker build -t your-registry/blog-backend:latest ./backend
docker build -t your-registry/blog-frontend:latest ./frontend
docker push your-registry/blog-backend:latest
docker push your-registry/blog-frontend:latest

2. 修改 K8s 配置

编辑以下文件中的占位符：

• k8s/backend/secret.yaml：数据库连接串、JWT 密钥、GitHub OAuth 参数、管理员 GitHub ID
• k8s/postgres/secret.yaml：PostgreSQL 密码
• k8s/backend/deployment.yaml：APP_URL 和 FRONTEND_URL
• k8s/ingress.yaml：你的域名
• k8s/kustomization.yaml：镜像仓库地址

3. 应用配置

kubectl apply -k k8s/

4. 网络说明

你的场景是：Caddy（TLS 终止）→ k3s Traefik（HTTP）→ frontend/backend

• 集群内 Ingress 使用 traefik.ingress.kubernetes.io/router.entrypoints: web（HTTP 80 端口）。
• Caddy 负责 HTTPS 证书和终止 TLS，反向代理到集群的 80 端口。
• 后端不做 TLS，不需要证书配置。
• Ingress 中 /api 路径转发到 backend，其余路径转发到 frontend。

安全注意事项

1. JWT_SECRET 生产环境必须替换为随机强密钥。
2. GitHub OAuth state：当前实现将前端 redirect URL 直接作为 state，存在开放重定向风险。后续建议对 state 做签名/加密。
3. Secret 管理：当前用 K8s Secret 明文存储，生产建议使用 Vault / Sealed Secrets / External Secrets Operator。
4. PostgreSQL：k3s 内使用 StatefulSet + PVC，建议配置定期备份（如 pg_dump CronJob 或 Velero）。

后续可扩展

• 接入对象存储（如 MinIO/S3）保存图片/附件。
• 引入全文搜索（Meilisearch / Elasticsearch）。
• GitHub Actions CI/CD 自动构建推送镜像。
• 文章阅读量统计。
• 评论通知 / Webhook。