LearnOS：打造AI原生的自托管在线学习平台，从部署到API实践

这次我们来看一个开源项目 LearnOS。它的定位很直接把 Coursera 这类在线学习平台做成开源版本并且能在你自己的电脑或服务器上跑起来同时把 AI 能力作为核心组件嵌入学习流程而不是事后加一个“Chat 问答框”。这个项目值得关注的点主要有几个第一开源可自托管课程数据、用户数据、学习记录都在自己手里不用上传到第三方平台第二AI 原生设计从学习路径规划、内容检索、测验反馈到作业批改都可能由 AI 驱动第三本地运行在局域网内可以搭建一套私有的“在线大学”适合企业内部培训、小团队知识管理、教育培训机构离线部署等场景。如果你之前研究过 Moodle、Canvas LMS 这类传统学习管理系统又想把 AI 能力真正接进教学流程那 LearnOS 是一个值得跟进的参考项目。这篇文章会围绕项目定位展开先梳理能力边界再给出一套本地部署、功能验证、接口调用和批量课程导入的完整思路。项目当前还在快速迭代阶段文章里的命令和配置属于通用模板具体路径、镜像名、环境变量需要以官方仓库 README 和实际版本为准。1. LearnOS 核心能力速览能力项说明项目类型开源在线学习平台Learning Management System核心定位AI 原生的本地版 Coursera开源情况开源项目可自托管部署主要功能课程管理、章节内容、学习进度、测验/作业、用户体系、AI 学习助手AI 能力AI 辅助学习路径规划、内容问答、知识检索、测验反馈等部署方式预计支持 Docker Compose 或源码运行具体以仓库文档为准数据存储数据库持久化可选 SQLite / PostgreSQL具体看项目实现硬件要求平台本身无需 GPU如接本地 AI 模型需按模型要求准备显存是否支持 API从项目定位看需要预留 REST API具体路径以源码为准是否支持批量任务课程批量导入、批量用户创建等需结合实际实现或二次开发适合场景企业内训、教育机构、离线教学环境、个人知识库课程化不适合场景追求零配置上手的非技术用户、需要大规模公有云 SaaS 功能的团队从项目名称来看“AI-native”是它和传统 LMS 最大的区别。传统学习平台里的 AI 往往是插件形式而 LearnOS 的理念是把 AI 揉进用户的完整学习闭环你学完一个章节AI 可以立刻根据你的掌握情况生成练习题你搜索一个概念AI 可以结合课内资料给出带上下文的解释你提交作业AI 可以按评分标准给出批改反馈。2. 适用场景与使用边界2.1 适用场景企业内部培训。很多公司需要搭建自己的培训平台但商业 LMS 年费不低且课程数据放在第三方平台未必符合合规要求。LearnOS 这类自托管方案可以把课程全部放在内网员工通过浏览器学习管理员统一管理课程和学习记录。教育培训机构。辅导机构、职业培训机构想把线下课程线上化可以用 LearnOS 搭建自己的课程门户课程内容、测验、学习进度都在自己服务器上方便和自有业务流程打通。个人知识管理课程化。你可能有大量笔记、教程、资料LearnOS 可以把这些内容结构化为一门门课程配合 AI 问答变成一个可交互的个人知识库。离线或内网环境。某些单位的网络环境不适合把数据传到外部 AI 服务但可以接入内部署的开源大模型。LearnOS 只要能配置本地模型地址就能在完全隔离的网络里使用 AI 功能。2.2 使用边界不是零配置 SaaS。自托管意味着你需要自己处理服务器、数据库、环境变量、网络端口、备份和升级技术要求比直接用在线版 Coursera 高很多。AI 能力依赖模型质量。AI 是原生能力但最终效果取决于你接入的模型。接 GPT 级别的商业 API 效果好接本地小尺寸模型可能要降级预期。课程内容版权要自己把关。如果导入第三方的课程、视频、教材务必确认授权不能把盗版课程直接架到自己的平台上。用户隐私和数据合规。学习平台上会有真实用户数据尤其是企业内部使用时涉及员工学习记录。自托管环境下服务器安全、数据加密、访问控制都要做踏实。AI 生成内容需要人工复核。测验题、作业反馈、学习建议都可能出现 AI 幻觉批量生成后不能直接分发必须有审核环节。3. LearnOS 本地部署环境准备在动手部署之前先整理一套通用的环境检查清单。LearnOS 具体依赖什么语言运行时要看仓库 README但下面这些项目通常都需要准备。3.1 操作系统与基础软件推荐使用 Linux 服务器比如 Ubuntu 22.04 LTS 或 Debian 12。Windows 和 macOS 也可以本地开发调试但长期跑服务还是 Linux 更稳。需要预装的软件取决于部署方式如果使用 Docker Compose只需要 Docker 和 Docker Compose 插件。如果使用源码方式运行大概率需要 Node.js20、Python3.10、包管理器 pnpm/yarn/npm、数据库服务。# Ubuntu/Debian 安装 Docker 和 Compose 插件通用步骤 sudo apt update sudo apt install -y docker.io docker-compose-v2 sudo systemctl enable --now docker docker --version docker compose version3.2 数据库准备学习平台离不开用户数据、课程数据、进度数据。轻量使用可能默认落 SQLite生产环境建议用 PostgreSQL。# 使用 Docker 启动 PostgreSQL 测试实例 docker run -d \ --name learnos-postgres \ -e POSTGRES_USERlearnos \ -e POSTGRES_PASSWORDlearnos_pass \ -e POSTGRES_DBlearnos \ -p 5432:5432 \ -v learnos_db:/var/lib/postgresql/data \ postgres:15如果使用源码方式运行需要把数据库连接串配置到环境变量里export DATABASE_URLpostgres://learnos:learnos_pass127.0.0.1:5432/learnos3.3 AI 服务配置LearnOS 既然是 AI 原生AI 服务地址是核心配置。通常有两种接法接云端 API。使用 OpenAI 兼容接口时通常需要配置 API Key、Base URL 和模型名。export AI_API_KEYsk-你的key export AI_BASE_URLhttps://api.openai.com/v1 export AI_MODELgpt-4o-mini如果使用国内大模型厂商的 OpenAI 兼容接口把 Base URL 换成厂商地址即可。接本地模型。如果内网部署可以用 Ollama、vLLM 等工具起一个本地模型服务再把 Base URL 指向本机。# 以 Ollama 为例仅示例实际模型选择按机器内存和显存决定 ollama pull qwen2.5:7b ollama serveexport AI_BASE_URLhttp://127.0.0.1:11434/v1 export AI_MODELqwen2.5:7b3.4 网络与端口规划LearnOS Web 服务预计监听一个 HTTP 端口常见是 3000 或 8080。数据库端口 5432 不要暴露到公网。如果使用 Nginx 反向代理预留 80/443。本地测试时可以通过 127.0.0.1 访问内网使用则绑定对应网卡 IP。# 检查端口占用 ss -tlnp | grep -E 3000|80804. LearnOS 安装部署与启动方式4.1 方式一Docker Compose 部署如果项目提供了官方 compose 文件这是最快的启动方式。git clone https://github.com/你的目标仓库/learnos.git cd learnos cp .env.example .env # 编辑 .env配置数据库、AI Key 等 docker compose up -d一个通用的 compose 模板长这样但镜像名和具体服务名一定要以官方文档为准version: 3.8 services: db: image: postgres:15 environment: POSTGRES_USER: learnos POSTGRES_PASSWORD: learnos_pass POSTGRES_DB: learnos volumes: - db_data:/var/lib/postgresql/data ports: - 5432:5432 app: image: learnos/learnos:latest environment: DATABASE_URL: postgres://learnos:learnos_passdb:5432/learnos AI_API_KEY: ${AI_API_KEY} AI_BASE_URL: ${AI_BASE_URL} AI_MODEL: ${AI_MODEL} ports: - 3000:3000 depends_on: - db volumes: db_data:启动后访问http://127.0.0.1:3000看到登录或注册页面说明服务起来了。4.2 方式二源码方式运行如果项目是单体仓库前端加后端一起管理典型的启动流程如下git clone https://github.com/你的目标仓库/learnos.git cd learnos # 安装依赖具体包管理器看仓库 lockfile 判断 npm install # 或 pnpm install # 配置环境变量 cp .env.example .env # 初始化数据库 npm run db:migrate # 启动开发服务 npm run dev生产环境一般需要先构建前端静态资源再由后端服务托管npm run build npm run start4.3 方式三反向代理与 HTTPS内网环境可以不用但如果需要从外网访问建议在 LearnOS 前面加一层 Nginx启用 HTTPS 和访问限制。server { listen 80; server_name learnos.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }4.4 启动后的初始检查启动完成后不要急着导入大量课程先确认以下几点Web 页面是否可以正常打开。数据库连接是否正常登录/注册是否报错。AI 配置是否生效发一句测试消息看返回。日志里有没有异常堆栈。# 查看服务日志 docker compose logs -f app5. LearnOS 功能测试与效果验证部署完成后按下面的维度做一轮功能测试。不需要一次全跑完但每个模块至少要摸一遍确认项目是否符合预期。5.1 平台启动与用户注册验证测试目的确认服务可用、用户体系正常。操作步骤打开http://127.0.0.1:3000。进入注册页创建管理员账号。登录后检查默认页面是否能正常加载课程列表。预期结果注册成功登录态保持没有 500 或数据库连接错误。常见失败原因数据库未初始化需要执行迁移命令。JWT 或会话密钥未配置登录后立即失效。前端构建产物缺失页面白屏。5.2 课程创建与章节管理验证测试目的验证课程结构是否符合你的预期比如课程是否支持章、节、多媒体、附件。操作步骤在管理后台点击“创建课程”。填写课程名称、简介、封面。添加第一章节写入一段正文。预览课程页面。预期结果课程保存成功前端展示正确。输入示例Markdown 内容# 第一章 认识 Python Python 是一种解释型、动态类型的高级编程语言。 ## 1.1 环境安装 访问官网下载安装包即可。判断成功标准课程预览页面能正常渲染 Markdown 正文章节导航生效。常见失败原因课程内容字段格式不兼容。封面上传大小超出后端限制。富文本编辑器资源加载失败多见于没有正确配置静态资源路径。5.3 用户学习流程与进度记录验证测试目的确认普通用户可以加入课程、标记章节完成、恢复学习进度。操作步骤创建第二个普通测试账号。用管理员账号发布一门课程。用普通账号加入课程。阅读第一章标记完成刷新页面确认进度是否保存。判断成功标准完成后进度条更新刷新后进度不丢。常见失败原因进度写入接口报错。浏览器本地存储和服务器存储混用换设备后进度不同步。前后端对章节 ID 的序列化不一致导致进度错位。5.4 AI 学习助手验证测试目的验证 AI 是否真的嵌入学习流程而不是空有设置项。测试维度在课程章节页提问AI 是否能结合课程内容回答。学完章节后AI 是否能生成测验题。输入错误的测验答案AI 是否能给出解释和下一步建议。AI 回答的延迟和平台页面是否能异步返回不阻塞其他操作。输入示例请根据第一章内容生成 5 道选择题覆盖 Python 环境安装和基础语法。预期结果AI 返回结构化题目并能在平台上以题目形式渲染。判断成功标准回答内容与课程资料相关不是泛泛而谈的通用答案。如果回答和课程内容完全无关说明检索环节没生效。常见失败原因向量检索没接AI 只能靠默认知识回答。API Key 过期。上下文长度超限长章节被截断。本地模型并发能力不足多人同时提问时排队。5.5 测验与作业批改验证测试目的确认测验提交、自动评分、AI 批改链路是否可用。操作步骤在课程中创建一份测验。设置客观题答案。用测试账号提交测验。查看系统评分和 AI 反馈。预期结果客观题正确计分主观题由 AI 给出反馈或进入人工批改流程。判断成功标准成绩入库用户能看到自己的得分和批改意见。常见失败原因评分规则没有配置完整。AI 批改超时。主观题没有进入待批改队列。5.6 批量课程导入测试测试目的验证是否能通过脚本或 API 批量创建课程而不是在页面上手工一条条添加。操作步骤准备一个课程目录每个 subdirectory 包含meta.json和content.md。调用批量导入脚本或后台命令。到平台页面检查是否生成对应课程。预期结果多门课程一次性导入成功内容完整。判断成功标准导入后课程列表中能看到全部课程点进去内容正常。常见失败原因课程文件编码不是 UTF-8中文乱码。字段名和接口不匹配。批量导入时触发数据库唯一约束冲突。6. LearnOS 接口 API 与批量任务设计学习平台一旦要投入实际使用接口能力就非常重要。你要考虑课程如何从已有系统同步过来、用户如何批量导入、学习数据如何导出分析。6.1 API 启动方式如果项目后端暴露 REST API通常和 Web 服务共用同一个服务端口。启动后可以先用健康检查接口确认curl http://127.0.0.1:3000/api/health返回 JSON 通常包含服务状态和数据库状态。6.2 常见接口路径设计不同项目的路由会不一样但学习平台常见的 REST 接口模式如下实际路径以源码为准资源方法作用/api/coursesGET获取课程列表/api/coursesPOST创建课程/api/courses/{id}GET获取课程详情/api/courses/{id}/chaptersPOST添加章节/api/usersPOST创建用户/api/enrollmentsPOST用户加入课程/api/progressGET/PUT获取/更新学习进度/api/ai/chatPOSTAI 对话/api/ai/quizPOST生成测验题6.3 API 调用示例以创建课程为例curl -X POST http://127.0.0.1:3000/api/courses \ -H Content-Type: application/json \ -H Authorization: Bearer 你的token \ -d { title: Python 入门, description: 面向初学者的 Python 课程, chapters: [ {title: 环境搭建, content: 安装 Python 解释器}, {title: 基础语法, content: 变量、数据类型、流程控制} ] }用 Python 调用同样可行import requests API_BASE http://127.0.0.1:3000/api TOKEN 你的token headers { Authorization: fBearer {TOKEN}, Content-Type: application/json, } payload { title: 数据库基础, description: SQL 与索引入门, chapters: [ {title: SQL 基础, content: SELECT、INSERT、UPDATE、DELETE}, {title: 索引原理, content: B 树与执行计划}, ], } resp requests.post(f{API_BASE}/courses, jsonpayload, headersheaders, timeout30) print(resp.status_code) print(resp.json())6.4 批量课程导入脚本批量导入不能逐条 curl要写成脚本加日志和失败重试。import json import os import time import requests API_BASE http://127.0.0.1:3000/api TOKEN 你的token COURSE_DIR ./courses headers { Authorization: fBearer {TOKEN}, Content-Type: application/json, } def import_course(meta: dict) - dict: resp requests.post( f{API_BASE}/courses, jsonmeta, headersheaders, timeout60, ) resp.raise_for_status() return resp.json() def main(): for filename in sorted(os.listdir(COURSE_DIR)): if not filename.endswith(.json): continue path os.path.join(COURSE_DIR, filename) with open(path, r, encodingutf-8) as f: meta json.load(f) for attempt in range(3): try: result import_course(meta) print(f[OK] {filename} - {result.get(id)} {result.get(title)}) break except requests.RequestException as exc: print(f[FAIL] {filename} 尝试 {attempt 1}/3: {exc}) time.sleep(2) if __name__ __main__: main()6.5 批量任务注意事项每个请求之间加间隔避免短时间大量请求压垮服务。导入失败的任务要能定位是哪个文件、哪个字段导致失败。遇到重复导入的情况要在脚本里做幂等判断比如先查课程是否已存在。大批量用户导入建议走 CSV 解析逐行校验邮箱格式和必填字段。定期扫描导入日志清理失败任务避免积压。7. LearnOS 资源占用与性能观察从项目定位看LearnOS 本身属于 Web 应用。平台自身的资源消耗主要来自前端静态资源、后端服务进程和数据库。硬件资源大头通常在 AI 侧。7.1 平台本身的资源占用后端服务和前端静态资源通常占用内存不高常规 2 核 4G 的服务器可以支撑小规模使用。数据库会随课程和用户量增长而变重建议开启慢查询日志定期清理日志表。如果课程包含大量视频和图片磁盘和带宽压力会明显上升。观察资源占用的方法# 查看进程资源 top -p $(pgrep -f learnos | head -1) # Docker 方式 docker stats # 数据库连接数 psql -U learnos -d learnos -c SELECT count(*) FROM pg_stat_activity;7.2 AI 推理资源占用这里要看 AI 是怎么接的如果 LearnOS 调用云端 API平台本身只负责转发和渲染显存占用可以忽略。如果接本地模型资源占用取决于模型大小。7B 量级模型量化后通常需要 6G 到 8G 显存13B 以上需要更大显存或纯 CPU 推理但 CPU 推理的响应速度会慢很多。如果接本地模型并支持批量生成测验题要注意并发请求对显存的压力必要时做请求排队。实际占用必须以你的模型版本、量化方式和机器配置为准不能按估算直接上线。7.3 性能优化策略前端层面用 Nginx 托管静态资源并开启 gzip。图片和视频走对象存储或单独目录不要全塞进数据库。后端层面AI 对话接口尽量走异步任务避免前端一直等待。高频读取的课程列表、进度数据可以加 Redis 缓存。批量导入课程时控制并发数量减少数据库锁冲突。数据库层面给课程表、章节表、学习进度表加上合理索引。定期执行VACUUM ANALYZE或等价的数据库维护操作。学习进度变化很频繁建议做合并写入或降级写入避免每次请求都立刻落库。7.4 如何判断平台是否“卡”不要只看 CPU 和内存。遇到页面卡顿优先看这几个指标接口响应时间用浏览器开发者工具看请求耗时超过 1 秒的接口要排查。数据库慢查询开启慢查询日志定位耗时 SQL。AI 接口耗时AI 回答慢通常不是平台性能问题而是上游模型响应慢。磁盘 IO如果大量上传视频磁盘带宽可能会成为瓶颈。8. LearnOS 常见问题与排查方法问题现象可能原因排查方式解决方案页面打开白屏前端静态资源未构建或路径错误打开浏览器控制台看资源加载状态重新构建前端检查静态资源路径配置启动后接口 500数据库未迁移或连接串错误查看服务日志和数据库连接执行数据库迁移修正 DATABASE_URL登录后请求 401JWT 密钥未配置或失效检查环境变量配置统一 SECRET_KEY重启服务AI 回答和课程无关向量检索未启用或索引为空检查是否配置了 embedding 模型重建课程文本索引AI 接口超时上游模型响应太慢或本地模型并发不足用 curl 直接测试 AI 接口限制并发请求换更快的模型调大超时时间中文乱码导入文件编码不是 UTF-8用 file 命令检查文件编码统一转 UTF-8 后重新导入批量导入卡住脚本没有重试机制或数据量过大查看后台任务队列和日志分批导入加超时和重试数据库连接耗尽连接池配置过小或存在慢查询查看数据库连接数和慢查询调大连接池优化慢查询本地模型显存不足模型超过显卡容量运行 nvidia-smi 查看显存换小尺寸模型或开启量化用 CPU 推理但接受性能下降端口冲突3000 端口被其他服务占用ss -tlnp | grep 3000修改 LearnOS 端口配置9. LearnOS 最佳实践与使用建议9.1 先跑通最小可用配置不要一开始就导入几百门课程、接上本地大模型。第一次部署按最低风险路径来用 Docker 起平台。接一个云端 API 模型成本低、响应快。手工创建一门测试课程。跑通 AI 问答和测验生成。确认整个流程没问题再考虑批量导入和本地模型。9.2 目录与数据管理自托管项目最怕数据丢失。建议这样规划/opt/learnos/ ├── .env ├── docker-compose.yml ├── data/ │ ├── postgres/ # 数据库数据卷 │ ├── uploads/ # 课程图片、视频、附件 │ └── backups/ # 定期备份 └── logs/ ├── app.log └── import.log备份时不要把数据库和上传文件分开考虑两者要一起备份否则课程内容和附件对不上。9.3 批量任务要带日志和重试批量导入课程、批量创建用户这类任务至少要记录任务开始时间和结束时间。每条数据的执行结果。失败原因和重试次数。幂等 ID避免重复执行时产生脏数据。9.4 AI 配置要分层开发环境用小模型成本低、响应快。生产环境按实际效果选更好模型。关键教学内容的 AI 反馈加入人工审核环节不要全自动分发到学生端。如果接多种模型建议在环境变量里区分“生成题目模型”和“对话模型”因为不同任务对模型能力要求不同。9.5 安全与合规平台如果暴露到公网必须启用 HTTPS并配置强密码策略。管理后台地址建议通过 Nginx 限制 IP 白名单访问。AI 接口涉及的知识库内容如果包含企业敏感资料要考虑模型服务的数据留存策略。对 AI 生成的学习资料和测验题目要定期抽查质量尤其是涉及事实性知识的科目。如果使用人脸识别、声音采集等扩展功能需要更严格的授权流程。当前基于课程内容的功能也要在用户协议里写明数据使用范围。9.6 更新策略自托管项目在快速迭代阶段不要盲目追最新版本。更稳妥的做法是阅读版本发布说明。在测试环境执行数据库迁移。备份生产数据库。分批次升级并观察日志。确定无异常后再切换流量。10. 总结与下一步LearnOS 最值得关注的不是“又有一个 LMS”而是它把 AI 纳入学习主流程的思路。课程管理、学习进度、测验反馈这些传统 LMS 都能做但“AI 根据课程内容生成测验、回答章节问题、给作业写评语”如果能在本地闭环完成那它就不是简单的课程管理系统而是能真正降低教学人力成本的 AI 原生学习平台。如果决定亲自试试最先要验证三件事一是 Docker 部署后页面能否正常打开二是课程创建和进度记录是否顺手三是 AI 问答是否能结合课程内容给出有用回答。第三点尤其重要很多人把模型接好之后发现回答和课程内容没关系那问题通常出在检索环节不在对话模型本身。最容易踩的坑有两个。一个是数据库迁移和密钥配置没做对导致服务起来了但登录和写入都报错另一个是本地模型和课程内容没有结合AI 看似接了实际只是套了一层通用对话壳。真正判断项目有没有价值就看 AI 是不是围绕课程内容在运转。后续可以扩展的方向也很多把学习进度数据导出做分析接入视频课程和章节测验开发浏览器插件提示每日学习任务对接企业内部 SSO 单点登录把 AI 批改接入人工复核工作流甚至给课程加 RAG 知识库让 AI 能引用具体章节原文回答问题。如果你想搭一套可控、数据在自己手里、AI 又能深入教学流程的学习平台LearnOS 值得收藏起来跟进。先用最小配置跑通再逐步加功能比一开始就上全套方案要稳得多。