EverRoom Gateway独立部署与REST API完整参考：健康检查、OpenAPI与数据目录

EverRoom Gateway独立部署与REST API完整参考健康检查、OpenAPI与数据目录【免费下载链接】EverRoomEverRoom - A workspace that remembers your projects, decisions, and sources.项目地址: https://gitcode.com/gh_mirrors/ev/EverRoomEverRoom 是一个能记住你的项目、决策与信息来源的智能工作区它的本地后端核心就是EverRoom Gateway——一个基于 Node.js 的 REST API 网关服务。本文面向新手带你完成 Gateway 的独立部署并掌握它的三大实用能力健康检查、OpenAPI 文档与数据目录查询。什么是 EverRoom GatewayEverRoom Gateway 是一个本地优先的后端网关用 Fastify 框架构建数据存储在本地 SQLite 中。在正式产品中它由桌面应用托管启动但你也可以把它作为一个独立的 Node.js 服务运行在自己的机器上供脚本、CI 任务或自研客户端调用。模块总览apps/gateway/README.md服务装配入口apps/gateway/src/server/create-server.ts三步完成 Gateway 独立部署 第一步安装依赖并生成数据库迁移进入仓库根目录后执行pnpm install pnpm db:generate第二步指定数据目录、端口与令牌启动pnpm dev -- --data-dir .data --port 3210 --token local-development-token三个关键参数参数作用--data-dir所有本地数据数据库、日志、安全凭据的根目录--port监听端口设为0时由系统随机分配--tokenBearer 认证令牌访问 API 的钥匙 生产环境建议为令牌生成高熵随机值并以--port 0启动避免端口冲突。第三步读取运行时清单确认就绪Gateway 就绪后会写入data-dir/runtime/gateway.json清单文件其中包含实际端口、令牌等信息。调用方应同时校验清单中的 PID 与健康端点因为进程非正常退出可能留下过期的运行时状态。健康检查端点速查 EverRoom Gateway 提供两个免认证的健康检查端点非常适合 K8s 探针、Docker HEALTHCHECK 或监控脚本实现见 apps/gateway/src/modules/system/routes.ts端点用途说明GET /v1/health/live存活探测进程能响应即为ok不访问数据库GET /v1/health/ready就绪探测会实际执行数据库查询数据库不可用时返回503 not_readyGET /v1/system/info版本信息返回服务名、版本、Node 版本与运行平台需令牌正常情况下响应形如{ status: ok, service: nxcore-gateway, version: 0.1.0, pid: 12345, uptimeSeconds: 87.2 }REST API 认证一个令牌走遍全站 除健康检查和文档页外所有 API 都要求 Bearer 令牌认证认证逻辑见 apps/gateway/src/server/auth.tscurl -H Authorization: Bearer local-development-token \ http://127.0.0.1:3210/v1/system/info令牌错误或缺失 →401 unauthorized业务错误统一返回error/message/requestId三字段结构requestId可直接用于日志检索打开 OpenAPI 交互式文档 启动后访问http://127.0.0.1:3210/docs即可看到由 Swagger UI 渲染的完整接口文档注册代码见 apps/gateway/src/server/create-server.ts所有端点按模块打标签system、files、documents、knowledge 等方便按领域浏览内置bearerAuth安全方案在页面右上角填入令牌即可直接在线调试该页面同样免认证适合分享给协作者快速上手数据目录结构一览 独立部署后所有数据都集中在--data-dir指定的目录中理解这份数据目录是运维 Gateway 的第一步路径内容runtime/gateway.json运行时清单端口、令牌、进程信息database/gateway.sqlite主数据库文档、房间、记忆等database/connectors.sqlite连接器独立数据库邮件、日程等记录logs/gateway.YYYY-MM-DD.N.log结构化 JSON 日志午夜滚动保留 30 份历史security/credentials.enc加密保存的凭据主密钥可通过环境变量覆盖connectors/documents/provider/id/连接器同步的 Markdown 文档recordings/供语音转写ASR使用的录音文件用 REST 接口查询文件数据目录Gateway 提供了/v1/files/catalog端点可以分页浏览已索引的本地文件目录路由定义见 apps/gateway/src/modules/files/routes.tscurl -H Authorization: Bearer token \ http://127.0.0.1:3210/v1/files/catalog?limit20offset0limit每页条数1–200默认 100offset偏移量用于翻页响应为{ items: [...], total: 总数 }可轻松实现全量遍历部署排障小贴士 ✅401 频繁出现确认请求头携带的是启动参数中的令牌而不是.env里的旧值/v1/health/ready返回 503检查database/目录权限与磁盘空间找不到端口读data-dir/runtime/gateway.json并核对清单 PID 是否仍存活日志定位按requestId在logs/当日日志中检索快速定位单次请求小结EverRoom Gateway 以极低的门槛就能独立跑起来一条启动命令、一个 Bearer 令牌、一份清晰的数据目录再配合免认证的健康检查与开箱即用的 OpenAPI 文档非常适合自建监控、编写自动化脚本或接入自研工具。建议结合 apps/gateway/README.md 中的检查命令pnpm typecheck/pnpm test/pnpm build持续保持服务健康。【免费下载链接】EverRoomEverRoom - A workspace that remembers your projects, decisions, and sources.项目地址: https://gitcode.com/gh_mirrors/ev/EverRoom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考