Skip to content
BranchesTags

Repository files navigation

LiveBoard

CI Node.js Next.js NestJS

LiveBoard 是一个面向课程团队的自托管教学工作台，将课程资料、课堂演示、在线练习、权限管理、论坛与 AI 助手放在同一套系统中。

项目目前处于持续开发阶段，适合本地试用和二次开发。生产部署前请完成安全配置检查，并替换全部默认凭据。

功能

  • 文档：以文件夹和内容块组织文档、教案、课程及练习资料。
  • 课件：将文档段落和练习组合成课件，支持键盘翻页和全屏展示。
  • 在线练习：创建题目、提交答案、自动评分和人工批改。
  • 文件：上传、预览、引用并追踪课程附件。
  • 论坛：使用版块、主题和回复组织课程交流。
  • AI 助手：基于用户有权访问的内容提供回答。
  • 权限体系：通过权限组向文件夹或文档授予管理、编辑、制作课件、查看或禁止访问权限。
  • 管理中心：管理用户、权限组、论坛、AI、存储和系统设置。

技术栈

层级 技术
Web Next.js 15、React 19、TypeScript
API NestJS 11、Prisma
数据 PostgreSQL 16、Redis 7
文件 MinIO
工程 pnpm workspace、Docker Compose、GitHub Actions

快速开始

环境要求

  • Node.js 22
  • pnpm 11
  • Docker Desktop 或兼容的 Docker 环境

本地开发

pnpm install
cp .env.example .env
pnpm infra:up
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm dev

服务地址：

服务 地址
Web http://localhost:3000
API 健康检查 http://localhost:4000/health
MinIO 控制台 http://localhost:9001

pnpm dev 会启动支持热更新的 Next.js 和 NestJS 开发服务器。PostgreSQL、Redis 与 MinIO 继续由 Docker 提供。

演示账号

执行种子数据后会创建以下本地账号：

账号 密码 用途
admin liveboard-admin 最高管理员
author liveboard-author 文档维护
lecturer liveboard-lecturer 课件与批改
learner liveboard-learner 学习与提交

这些账号仅由本地 demo seed 创建。生产 bootstrap 不会创建它们，Release 构建也会将 NEXT_PUBLIC_SHOW_DEMO_ACCOUNTS 固定为 false。

生产部署

LiveBoard 支持两种受支持的生产部署目标：

  • 自托管（默认）：GitHub Release 自解压单文件包，Docker Compose + MinIO / 阿里云 OSS，详细见下方与 Ubuntu 24.04 单文件部署教程。
  • Vercel + Cloudflare R2：apps/web 与 apps/api 部署为两个 Vercel Project，PostgreSQL/Redis 使用托管服务，对象存储固定为 R2。业务行为由 DEPLOYMENT_TARGET=vercel 决定；Vercel 下大文件由浏览器直传 R2，每日 Cron 配合 R2 Lifecycle 清理过期上传。详细见 Vercel + R2 部署教程 与 数据迁移手册。

自托管发布

生产环境只保留一种自托管发布方式：GitHub Release 自解压单文件包。服务器不拉取源码、不构建镜像，也不直接访问 Docker Hub 或 npm registry。

推送 v* 标签后，Release 工作流会构建 Linux AMD64 的 API/Web 和固定版本基础镜像，并生成唯一资产：

liveboard-<version>-linux-amd64.run

用户在电脑下载该文件并上传到服务器 /opt，然后执行：

sudo sh /opt/liveboard-v0.3.0-linux-amd64.run install

将文件名替换为实际下载的版本。安装包会校验并解压自身，按需安装 Ubuntu 基础依赖，生成安全密钥，导入离线镜像，备份 PostgreSQL，执行 migration，配置 Nginx 并等待 API/Web 健康。空数据库会创建唯一的随机密码最高管理员；凭据在总结最后醒目显示，并保存到权限为 600 的 /opt/liveboard/initial-admin-credentials.txt。首次登录并修改密码后应删除该文件。生产过程不运行 demo seed。

安装完成后可使用固定管理命令：

sudo liveboard status
sudo liveboard doctor
sudo liveboard logs
sudo liveboard restart

最高管理员可进入“管理中心 → 系统设置 → HTTPS”，为指向本服务器的域名或服务器公网 IPv4 一键签发证书。域名证书使用常规 Let’s Encrypt profile；公网 IPv4 使用 shortlived profile，证书有效期约 6 天，因此应保持自动续期开启。系统优先使用 ACME HTTP-01；如果公网 TCP 80 或 HTTP Host 被阻断，则自动改用 TLS-ALPN-01 通过 TCP 443 验证，不依赖域名服务商。发布包已离线携带固定版本的 ACME 客户端，服务器配置时不需要下载程序。只有拿到有效证书且 Nginx 校验和本机 HTTPS 探测均成功后才会切换配置。

HTTPS 面板可以单独开启或关闭自动续期，也可以随时维护 HTTP 访问设置。HTTPS 启用时，这些地址只作为降级预案保存，不会改动当前证书、Nginx HTTPS 或续期任务；HTTP 模式下，修改会先经过地址校验和 nginx -t，成功后再应用。首选地址用于停用后的浏览器跳转，最多还可登记 7 个域名或公网 IPv4 作为备用 Host。停用会使用已保存的预案，把 SESSION_COOKIE_SECURE 改回 false，将全部已登记地址写入 WEB_ORIGIN，并重新载入 API/Web；浏览器切换到 HTTP 后需要重新登录。关闭自动续期不影响手动执行续期；定时任务仍会每天读取配置，但在开关关闭时不会联系证书机构。

也可在服务器执行同一套操作：

sudo liveboard https status
sudo liveboard https enable --domain board.example.com --email admin@example.com
sudo liveboard https enable --domain 8.166.143.156 --email admin@example.com
sudo liveboard https http-access --primary 8.166.143.156 --allow board.example.com
sudo liveboard https auto-renew off
sudo liveboard https auto-renew on
sudo liveboard https renew
sudo liveboard https disable

为兼容旧操作，https disable 仍接受 --http-host 和重复的 --allow 参数；建议先使用 https http-access 保存降级预案，再直接执行 https disable。

升级时上传新的 .run 文件，不需要手动解压：

sudo sh /opt/liveboard-v0.3.1-linux-amd64.run upgrade

升级沿用 /opt/liveboard/.env、管理员账号、数据库和对象存储卷；执行 migration 前会创建 PostgreSQL 备份，全部健康检查通过后才切换 /opt/liveboard/releases/active。

清理旧版本前可以先预览：

sudo liveboard clean --dry-run
sudo liveboard clean
sudo liveboard clean --keep 3 --packages

默认保留当前及上一个版本。清理只处理 LiveBoard 旧版本目录和对应的版本化 API/Web 镜像；--packages 额外清理 /opt 下的旧 .run/.tar.gz 安装包，不会删除数据库备份或数据卷。

可恢复卸载：

sudo liveboard uninstall

卸载会停止并删除 LiveBoard 容器、应用镜像、版本文件并禁用 Nginx 站点，但保留 /opt/liveboard/.env、数据库备份和 PostgreSQL/Redis/MinIO 命名卷。重新上传发布包并执行 install 可接回原数据。普通卸载不提供彻底删除业务数据的选项。

管理命令完整帮助：

liveboard help

完整步骤见 Ubuntu 24.04 单文件部署教程。 部署路线的取舍、已删除兼容代码和保留边界见 生产部署链路复盘。

Compose 的 PostgreSQL、Redis、MinIO、API 和 Web 端口只绑定 127.0.0.1，公网访问必须经过由安装器管理的 Nginx 配置。升级不会覆盖已有的 LiveBoard Nginx 配置。HTTP IP 部署使用 SESSION_COOKIE_SECURE=false；一键启用 HTTPS 后会自动改为 true。

PostgreSQL 备份不包含 MinIO 上传文件。生产环境还应为 minio-data 配置独立卷快照或对象存储备份。不得使用 docker compose down -v 更新或停止服务。

常用命令

pnpm dev          # 启动 Web 与 API 开发服务器
pnpm dev:web      # 只启动 Web
pnpm dev:api      # 只启动 API
pnpm infra:up     # 启动 PostgreSQL、Redis、MinIO
pnpm infra:down   # 停止 Compose 服务

pnpm db:generate  # 生成 Prisma Client
pnpm db:migrate   # 创建并执行 Prisma migration
pnpm db:reset     # 重建本地测试数据库并重放 migrations
pnpm db:seed      # 写入本地演示数据

pnpm format       # 格式化代码
pnpm typecheck    # TypeScript 检查
pnpm test         # 运行测试
pnpm build        # 构建全部包
pnpm validate     # 执行完整提交前检查

项目结构

liveboard/
├── apps/
│   ├── api/                 # NestJS API、Prisma 和种子数据
│   └── web/                 # Next.js App Router 前端
├── packages/
│   └── shared/              # 前后端共享类型、权限和评分逻辑
├── infra/nginx/             # Nginx 示例配置
├── docs/                    # 部署教程
├── docker-compose.yml
├── AGENTS.md                # Codex/开发代理工作约定与开发纪要
└── README.md

主要页面：

功能 路由
AI 助手 /app/ai
文档 /app/content
文档查看 /app/content/:id
文档编辑 /app/content/:id/edit
课件 /app/teaching
课件展示 /app/teaching/:id/present
文件 /app/library
在线练习 /app/exercises
论坛 /app/forum
管理中心 /app/admin

权限模型

系统角色分为 super_admin、admin 和 member。最高管理员拥有全站权限，管理员负责内容与成员管理，普通用户的具体资源权限通过权限组授予：

权限 能力
owner 管理内容与授权
editor 编辑内容
lecturer 查看并使用授课功能
viewer 查看已发布内容
no_access 显式禁止访问

所有资源访问都必须经过后端权限检查；前端隐藏按钮仅用于改善体验，不作为安全边界。

环境变量

复制 .env.example 后按环境修改。常用变量：

变量 说明
WEB_ORIGIN 允许携带凭据访问 API 的前端来源
NEXT_PUBLIC_API_URL 浏览器访问 API 的公开地址
DATABASE_URL PostgreSQL 连接地址
POSTGRES_DB PostgreSQL 数据库名
POSTGRES_USER PostgreSQL 用户名
POSTGRES_PASSWORD PostgreSQL 密码
REDIS_URL Redis 连接地址
TRUST_PROXY_HOPS API 前可信反向代理层数
SESSION_SECRET 会话签名密钥
AI_ENCRYPTION_KEY 数据库内 AI API Key 加密密钥
AI_RATE_LIMIT_MAX_REQUESTS 单用户 AI 限流窗口内最大请求数
AI_RATE_LIMIT_WINDOW_SECONDS AI 限流窗口秒数
AI_MAX_CONCURRENT_PER_USER 单用户 AI 最大并发请求数
BACKUP_RETENTION_COUNT 保留的 PostgreSQL 部署备份数量
SESSION_COOKIE_SECURE 是否只通过 HTTPS 发送会话 Cookie
AUTH_MODE local、hybrid 或 hflive_oidc
HFLIVE_* HFLive OIDC、Directory、webhook 与 break-glass 服务端配置
MINIO_* MinIO 地址、凭据和 bucket
NEXT_PUBLIC_SHOW_DEMO_ACCOUNTS 是否在登录页显示演示账号

不要提交 .env、真实密码、API Key、数据库备份或用户上传内容。

HFLive Auth 的模式、端点、发布顺序和回滚边界见 HFLive Auth 后端接入。

生产部署检查

  • 使用 Release 脚本自动生成的 PostgreSQL、MinIO、会话和 AI 加密密钥。
  • 生产初始化只创建一个随机密码最高管理员，不运行 demo seed。
  • 关闭登录页演示账号提示并重新构建 Web。
  • 使用 HTTPS，避免直接向公网开放数据库、Redis、MinIO 和 API 管理端口。
  • 确认 Compose 发布端口仍只绑定 127.0.0.1，公网安全组仅开放 SSH、HTTP 和 HTTPS。
  • 使用 GitHub Release 单文件包更新，并为 MinIO 配置独立备份。
  • 根据用户规模调整内置 AI 限流参数；公网入口仍建议增加网关级总量保护。
  • 所有 schema 变更都提交 Prisma migration；生产环境由 migrate 服务自动执行 prisma migrate deploy，不使用 db push。

参与开发

  1. 从 main 创建短生命周期分支。
  2. 完成修改后运行 pnpm validate。
  3. PR 中说明问题、方案、数据迁移、验证结果；涉及 UI 时附桌面端和移动端截图。
  4. 不提交生成目录、本地数据或秘密配置。

面向开发代理的具体约定、历史决策和易错点维护在 AGENTS.md。

About

智能的线上教学系统，集合团队文档、论坛、测验等功能，适用于中小型团队协作。

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Contributors

Languages