bensz-channel 项目介绍

1 这是什么？

bensz-channel 是一个参考 QQ 频道交互形态的 Web 社区平台，基于 Laravel + Better Auth + PostgreSQL + Redis + Docker 构建，当前版本 v1.20.0。

左侧频道导航，中间内容流，右侧社区信息——整体交互逻辑和 QQ 频道非常接近，但完全自托管，数据在自己手里。

---

2 核心能力

2.1 内容架构

• 频道首页、文章详情、右侧社区信息栏
• 内置不可删除的「精华」与「未分类」系统频道
• 管理员可一键将文章设为置顶或精华，首页优先展示置顶文章，「精华」频道聚合所有精华内容
• 文章与评论均支持 Markdown 渲染

2.2 登录体系

支持四种登录方式，可在后台按需开关：

方式	说明
邮箱 + 验证码	通过 Better Auth 自托管 OTP 服务
邮箱 + 密码	直接账号密码登录
微信扫码	默认演示模式，可切换真实微信开放平台 OAuth
QQ 扫码	默认演示模式，可切换真实 QQ 互联 OAuth

2.3 管理员后台

• 文章 CRUD、频道管理（含拖拽排序、顶栏显示控制）
• 用户管理：修改资料、角色切换，支持稳定用户 ID 检索
• 站点设置：站点名称/标语、登录方式开关、静态资源 CDN 配置
• SMTP 配置：后台直接维护全站邮件投递参数，并可一键测试

2.4 订阅能力

• SMTP 邮件订阅：注册用户可订阅全部/指定版块新文章，以及评论 @ 提醒
• RSS 订阅：全站 ，单频道

2.5 游客静态访问

未登录用户优先命中预构建静态 HTML（含 压缩版），登录后回退到 PHP 动态界面，兼顾性能与功能。

2.6 DevTools 远程管理

内置 RESTful API，配合 skill，可让 Claude Code、Codex CLI 等 Vibe Coding 工具通过 API 密钥远程管理频道、文章、评论和用户——就像你现在看到这篇文章，就是通过 DevTools 发布的。

---

3 技术栈

层级	方案
Web 应用	Laravel 12 + Blade + Tailwind CSS
认证服务	Better Auth + Express
数据库	PostgreSQL 17
缓存	Redis 7
Web 服务	Nginx + PHP-FPM
前端构建	Vite 7
本地邮件	Mailpit
部署	Docker Compose

---

4 快速部署

cp config/.env.example config/.env
./scripts/compose.sh up --build -d

启动后访问：

• 站点首页：http://localhost:6542
• Mailpit（本地邮件预览）：http://localhost:8025

默认管理员：邮箱 [email protected]，密码 admin123456。

Docker 启动只执行数据库迁移与系统基础初始化，不会自动灌入示例数据。如需演示数据，手动执行：

docker compose exec web php artisan db:seed

---

5 目录结构

bensz-channel/
├── config/ # 根配置：config.toml 放非密钥，.env 放密钥
├── scripts/ # 配置导出与 Docker Compose 包装脚本
├── app/ # Laravel 应用源码
├── auth-service/ # Better Auth 自托管认证服务
├── docker/ # Dockerfile、Nginx、Supervisor 配置
├── docker-compose.yml
├── data/ # Docker 持久化数据目录（自动创建，Git 忽略）
└── config.yaml # 项目版本单一事实来源

---

6 数据持久化

所有运行时数据显式挂载到 ./data/ 目录：

• ./data/postgres — PostgreSQL 数据
• ./data/redis — Redis AOF
• ./data/mailpit — Mailpit 数据库
• ./data/web/ — Laravel 运行时存储与静态页面输出

git pull 后重新 ./scripts/compose.sh up --build -d 不会覆盖现有业务数据。

---

7 后续可扩展方向

• 接入真实微信 / QQ OAuth 扫码平台
• 帖子列表分页、全文搜索、消息通知
• 频道更完整的权限模型与内容审核流程