Project NOMAD开发环境搭建贡献者从Fork到本地运行的完整指南【免费下载链接】project-nomadProject NOMAD is an offline-first knowledge and education server. Wikipedia, thousands of books, courses, maps, and optional local AI, all running on hardware you own with no internet required.项目地址: https://gitcode.com/GitHub_Trending/pr/project-nomadProject NOMAD 是一个离线优先的本地知识与教育服务器整合了离线维基百科、数千本书籍、课程、地图和可选的本地 AI。如果你是首次参与贡献本文将带你完成Project NOMAD 开发环境搭建的全部流程——从 Fork 仓库到本地跑起 Command Center 控制台让你在动手改代码之前先拥有一个可用的开发沙盒。 先认识项目NOMAD 是什么、由什么构成在写第一行代码前花两分钟了解整体架构会让后续工作事半功倍。NOMAD 本质上是一个管理中枢Command Center API通过 Docker 编排一堆容器化的工具能力技术栈说明后端AdonisJS (Node.js) MySQL Redis位于 admin/ 目录含路由、控制器、队列任务前端React Inertia.js TailwindCSS位于 admin/inertia/离线内容Kiwix (ZIM 文件)离线维基百科与参考书本地 AIOllama Qdrant (RAG)内置 AI 聊天与知识库语义检索离线地图ProtoMaps可下载区域地图教育平台Kolibri离线课程与进度跟踪完整能力介绍见 README.md 的How It Works章节。 关键认知NOMAD 高度依赖 Docker。官方在 CONTRIBUTING.md 中特别建议——不要在开发机上同时安装一个 Release 版本的 NOMAD端口、数据卷和资源容易冲突。请让开发环境独立运行。✅ 环境前置检查一份完整的清单开发环境搭建前对照以下清单逐项确认操作系统Debian 系推荐 Ubuntu 26.04 LTS也支持 24.04 LTS / Debian 12权限拥有sudo/root 权限Docker已安装且正在运行Docker 是 NOMAD 的核心依赖Node.js建议 Node 22官方 Dockerfile 基于node:22-slim构建Git用于 Fork、分支与提交稳定的网络连接下载依赖时需要官方贡献指南的完整前置条件见 CONTRIBUTING.md 的Prerequisites小节普通用户的系统要求可参考 admin/docs/getting-started.md。 Fork 并克隆仓库本地开发的第一步第 1 步Fork 仓库在仓库页面右上角点击Fork把项目复制到你自己的账号下。第 2 步克隆你的 Fork 到本地git clone https://gitcode.com/GitHub_Trending/pr/project-nomad project-nomad cd project-nomad第 3 步添加 upstream 远程源这样你就能随时同步官方主仓的最新代码git remote add upstream https://gitcode.com/GitHub_Trending/pr/project-nomad第 4 步切到开发分支dev官方要求所有 PR 都提交到dev分支本地开发也应基于它git checkout dev 快速看懂代码结构三大核心目录project-nomad/ ├── admin/ # 后端 前端Command Center 全部代码 │ ├── app/ # 控制器、服务、模型、队列任务 │ ├── inertia/ # React 前端页面与组件 │ ├── database/ # 数据库迁移与种子数据 │ ├── docs/ # 应用内置文档Markdown │ └── tests/ # 单元测试与功能测试 ├── collections/ # 内容数据源 JSON病症、天然疗法、地图等 └── install/ # 安装/维护脚本与 Docker Compose 模板几个值得留意的文件admin/package.json所有开发脚本都在这里后文会用到admin/.env.example环境变量模板配置.env的依据install/management_compose.yamlDocker Compose 编排模板admin MySQL Redis 辅助容器admin/inertia/components/共享 UI 组件库改前端时优先复用不要手搓新组件 本地跑起来从 .env 到 Command Center 仪表盘以下命令均在admin/目录下执行。第 1 步安装依赖cd admin npm install第 2 步创建环境变量文件cp .env.example .env打开.env确认几项关键配置模板来自 admin/.env.example变量说明注意PORT服务端口默认8080APP_KEY应用密钥必须至少 16 位否则容器/服务启动校验会失败DB_*MySQL 连接默认指向 localhost:3306 的nomad库REDIS_*Redis 连接默认 localhost:6379NOMAD_STORAGE_PATH内容存储路径存放 ZIM、地图等开发时指向本地任意目录即可第 3 步准备数据库与 Redis最省心的做法是直接参考 install/management_compose.yaml 中mysql和redis两个服务的定义用 Docker 单独起这两个依赖docker run -d --name nomad-dev-mysql \ -e MYSQL_ROOT_PASSWORDpassword \ -e MYSQL_DATABASEnomad \ -p 3306:3306 mysql:8.0 docker run -d --name nomad-dev-redis \ -p 6379:6379 redis:7-alpine⚠️ 如果改动了 MySQL/Redis 的端口或密码记得同步修改.env中的DB_*与REDIS_*变量两者必须一致。第 4 步启动开发服务器带热更新npm run dev该命令实际执行node ace serve --hmr修改 admin/inertia/ 下的前端代码或 admin/app/ 下的控制器都能即时生效。第 5 步可选启动队列 worker下载、模型导入、基准测试等长任务跑在队列里。需要完整体验这些功能时另开一个终端npm run work:all # 启动全部队列的 worker第 6 步打开浏览器验证访问http://localhost:8080看到 Command Center 页面即搭建成功。首次启动可运行 Easy Setup 向导熟悉界面 提示本地开发版没有注入 Creator Packs 密钥等生产配置部分付费内容 UI 不会显示属正常现象见 Dockerfile 中CREATOR_PACKS_APP_KEY相关注释。 提交前必做测试、Lint 与类型检查官方在 CONTRIBUTING.md 中明确要求提交前要在本地对运行中的 NOMAD 实例测试你的改动。三件套命令npm test # 运行测试node ace test npm run lint # ESLint 代码检查 npm run typecheck # TypeScript 类型检查另外两个高频维护脚本npm run gen:curated-data从 collections/ 的 JSON 数据源重新生成 admin/app/data/ 下的 TypeScript 数据模块。如果你改动了collections/*.json如病症、天然疗法数据务必运行它避免 JSON 与生成的.ts漂移——Docker 构建时也会自动执行这一步。 贡献工作流从同步上游到提交 PR1️⃣ 开工前先同步上游Rebase 优先官方偏好干净的线性历史同步命令git fetch upstream git checkout dev git rebase upstream/dev2️⃣ 创建描述性功能分支git checkout -b fix/issue-123 # 或 git checkout -b feature/add-new-tool3️⃣ 写代码遵守 UI 一致性规范改前端时牢记用户友好至上原则复用共享组件需求使用避免开关类设置Switch裸input typecheckbox悬停帮助InfoTooltip自定义 tooltip弹窗/确认框StyledModal手写遮罩层文本输入Input裸input区块标题StyledSectionHeader随意写 heading组件都在 admin/inertia/components/动手前先 grep 一下有没有现成的。4️⃣ Conventional Commits 提交信息提交信息必须遵循 Conventional Commits 格式type(scope): descriptionfeat(ui): add dark mode toggle to Command Center fix(api): resolve container status not updating after restart docs: update hardware requirements in README常用 typefeat新功能、fix修 bug、docs文档、refactor重构、chore构建/依赖、test测试。5️⃣ 推送并开 PR目标分支devgit push origin your-branch-name开 PR 时的三个要点说明改动内容和原因关联 issue如Closes #123——非平凡改动必须对应 issue没有 issue 的 PR 可能被直接关闭描述测试步骤与环境细节保持对评审反馈的响应⚡例外拼写修正、文档澄清、一行且原因明显的 bug 修复属于平凡修改可直接提 PR无需先开 issue。 常见坑点排查清单问题原因与解法服务启动报校验错误APP_KEY不足 16 位重新生成一个随机长字符串端口冲突8080 被占用——大概率是机器上跑了 Release 版 NOMAD停掉它或改.env中的PORT数据库连接失败.env的DB_*与 Docker 里 MySQL 的端口/密码不一致逐项对齐改了 JSON 但界面没变化忘记运行npm run gen:curated-data重新生成数据模块前端布局/弹层异常类型检查发现不了这类问题一定要在真实浏览器里打开页面验证并试多种窗口宽度想测自动更新逻辑无需真实升级在admin/下运行node ace auto-update:dry-run --scenarios可离线跑完整决策流程详见 README.md 下一步本地环境跑通后你可以浏览 admin/docs/ 中的内置文档熟悉产品功能与 API 参考阅读 admin/tests/ 下的测试用例学习项目测试风格去 issue 列表找一个good first issue按本文流程走一遍完整贡献闭环祝开发顺利欢迎一起把 Project NOMAD 做得更好 【免费下载链接】project-nomadProject NOMAD is an offline-first knowledge and education server. Wikipedia, thousands of books, courses, maps, and optional local AI, all running on hardware you own with no internet required.项目地址: https://gitcode.com/GitHub_Trending/pr/project-nomad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考