Huly 本地开发环境搭建：使用 dev/local-mongo 在宿主机运行 MongoDB 数据库

Huly 本地开发环境搭建使用 dev/local-mongo 在宿主机运行 MongoDB 数据库【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platformdev/local-mongo 是 Huly 仓库中一套面向开发者的本地 MongoDB 部署方案它让开发者绕过 Docker volume 中看不见摸不着的数据库改为在宿主机目录~/.mongo下直接运行 mongod并配套一键启动、停止、数据导出与导入脚本。读完本文你将掌握如何用start.sh/stop.sh管理本地数据库、如何用dump.shimport.sh完成从 Docker volume 版 MongoDB 的平滑迁移以及rush docker:local是如何让整套 Docker 容器account、front、transactor、collaborator 等通过huly.local主机名指向这台本地 MongoDB 的。一、为什么需要本地 MongoDBHuly 的 Docker 编排默认把 MongoDB 也容器化数据落在 Docker 管理的 volume 里。对于日常开发调试这种做法的痛点很明显数据不透明数据库文件深藏在 Docker volume 中不便于直接查看、备份和对比容器重建代价高一旦容器被重建或 volume 被清理本地开发数据可能一并丢失排查问题绕路想用mongosh直接探查数据、执行修复脚本时总要先进容器或额外暴露端口。dev/local-mongo 正是为此提供的替代方案MongoDB 以普通进程运行在宿主机上数据存放在~/.mongo/dataHuly 各容器通过huly.local:27017访问它。数据库对开发者完全透明容器可以随意重建而不影响数据。整套方案由仓库 dev/local-mongo 目录下的 6 个文件组成文件作用start.sh以mongod守护进程方式启动本地数据库stop.sh通过mongosh优雅关闭本地数据库mongod.confmongod 运行时配置日志、存储引擎、网络绑定dump.sh将本地 MongoDB 全量导出到dump/目录gzip 压缩import.sh将dump/目录的数据全量导入本地 MongoDBdocker-compose.yaml指向本地 MongoDB 的整套 Huly 服务编排二、快速开始启动与停止本地数据库2.1 启动./start.shstart.sh 内部实际做了三件事mkdir -p ~/.mongo/data mongod --config ./mongod.conf --dbpath ~/.mongo/data --directoryperdb --logpath ~/.mongo/mongod.log --fork # --replSet rs0创建数据目录~/.mongo/data若不存在以--fork方式后台守护启动 mongod日志写入~/.mongo/mongod.log脚本末尾注释了--replSet rs0与一段初始化副本集的mongosh代码——当前单机开发模式下副本集被注释禁用若后续需要开启例如启用事务或需要副本集语义的功能取消注释并按提示等待rs.initiate()完成即可。几个关键启动参数的含义--dbpath ~/.mongo/data数据库文件目录注意这里用绝对路径覆盖了配置文件中的相对路径--directoryperdb每个数据库独立目录存放便于按库管理文件--fork后台守护运行终端关闭后数据库依然存活--logpath ~/.mongo/mongod.log运行日志输出位置排查启动失败或连接异常时优先查看此文件。2.2 停止./stop.shstop.sh 只有一行通过mongosh向 admin 库发送关闭指令属于优雅停机mongosh --eval db.getSiblingDB(admin).shutdownServer()相比直接kill进程这种方式会让 mongod 完成数据刷盘与日志落盘避免数据文件损坏。2.3 验证启动后可用以下命令确认服务正常mongosh mongodb://localhost:27017 --eval db.runCommand({ ping: 1 }) # 预期输出{ ok: 1 }数据文件默认位于~/.mongo/data日志位于~/.mongo/mongod.log。三、迁移从 Docker volume 版 MongoDB 到本地 MongoDB如果你的开发环境之前是 Docker volume 中的 MongoDB现在想切到本地实例readme 给出的迁移路径是三步走./dump-docker.sh # 导出 Docker 版 MongoDB 的全部数据库 ./start.sh # 启动本地 MongoDB数据目录 ~/.mongo/data ./import.sh # 把导出的数据导入本地 MongoDB注意readme 中写的是dump-docker.sh而当前仓库实际提供的脚本文件名为 dump.sh执行时以仓库实际文件为准即./dump.sh。3.1 第一步导出dump.sh./dump.shdump.sh 的实现为mongodump --urimongodb://localhost:27017 --gzip --out dump $--gzip导出数据以 gzip 压缩大幅节省磁盘空间--out dump输出到当前目录下的dump/$透传附加参数例如可以用--db dbName只导出某个数据库用--excludeCollection排除集合。需要说明的是迁移第一步的本质是从旧环境导出。若旧库是 Docker 容器内的 MongoDB可将本脚本配合docker exec使用或手动把mongodump指向旧库的 URI例如mongodump --urimongodb://容器地址:27017 --gzip --out dump完成对旧实例的导出。3.2 第二步启动本地数据库./start.sh确保本地 mongod 已按上文方式启动并监听27017端口。3.3 第三步导入import.sh./import.shimport.sh 的实现为mongorestore --urimongodb://localhost:27017 --drop --gzip ./dump $--drop导入前先删除目标库中的同名集合避免新旧数据叠加保证导入结果与 dump 时一致--gzip与导出时的压缩格式对应./dump指定 restore 数据源目录$同样支持附加参数透传。整个迁移链路与仓库 common/scripts/mongo_dump.sh / mongo_restore.sh 中使用的工具一致均基于mongodump/mongorestore--gzip表明这是 Huly 开发体系中标准的 MongoDB 数据搬运方式。四、mongod.conf 配置详解本地实例的核心配置集中在 mongod.conf值得逐段解读systemLog: destination: file path: .mongo/mongo.log logAppend: true # replication: # oplogSizeMB: 128 storage: dbPath: .mongo/data directoryPerDB: true wiredTiger: engineConfig: directoryForIndexes: true cacheSizeGB: 2.0 net: bindIp: 127.0.0.1, ::1 ipv6: true4.1 systemLog日志策略destination: file日志写入文件而非标准输出path: .mongo/mongo.log注意这是相对于启动时工作目录的路径相对路径。start.sh 中通过--logpath ~/.mongo/mongod.log的绝对路径覆盖了它因此实际运行日志最终落在~/.mongo/mongod.loglogAppend: true日志追加而非每次启动覆盖便于保留历史记录。4.2 storage存储引擎与性能dbPath: .mongo/data默认数据目录相对路径start.sh 会用绝对路径~/.mongo/data覆盖directoryPerDB: true每个数据库一个子目录wiredTiger.engineConfig.directoryForIndexes: true索引与数据文件分目录存放wiredTiger.engineConfig.cacheSizeGB: 2.0WiredTiger 缓存上限 2 GB。该值直接决定 MongoDB 的内存占用与读写性能在开发机上如果内存紧张可以调低需要跑大量数据时则可适当调高。4.3 net网络绑定bindIp: 127.0.0.1, ::1仅绑定本机回环地址IPv4 与 IPv6不会对外网开放这是本地开发的安全默认值ipv6: true启用 IPv6 监听配合::1回环地址。4.4 replication副本集默认禁用配置中replication段整体被注释oplogSizeMB: 128。这意味着默认运行的是单节点非副本集模式与 start.sh 中--replSet rs0被注释的状态保持一致。如果需要副本集语义需要同时打开这两处。五、让整套容器指向本地 MongoDBrush docker:local本地数据库就绪后最常用的一条命令是rush docker:localreadme 中对其作用的描述是Will up all necessary containers and point them into local mongo database即启动 Huly 所需的全部容器并把它们的数据库连接指向这台本地 MongoDB。这个指向的机制藏在 dev/local-mongo/docker-compose.yaml 中。打开文件可以看到几乎所有核心服务的环境变量都统一指向huly.local:27017服务关键环境变量节选作用accountMONGO_URLmongodb://huly.local:27017?compressorssnappy账号服务collaboratorMONGO_URLmongodb://huly.local:27017?compressorssnappy、MONGO_OPTIONS{appName:collaborator,maxPoolSize:2}协同编辑frontMONGO_URLmongodb://huly.local:27017?compressorssnappy、MONGO_OPTIONS{appName:front,maxPoolSize:1}前端网关transactorMONGO_URLmongodb://huly.local:27017?compressorssnappy、MONGO_OPTIONS{appName:transactor,maxPoolSize:10}事务/同步核心printMONGO_URLmongodb://huly.local:27017?compressorssnappy打印服务signMONGO_URLmongodb://huly.local:27017电子签名aiBotMONGO_URLmongodb://huly.local:27017AI 机器人几点值得注意的实现细节huly.local是宿主机别名在 dev/docker-compose.yaml 等编排中各服务都配置了extra_hosts: huly.local:host-gateway将huly.local解析到宿主机Docker Desktop / 新版 Docker Engine 的host-gateway特性。因此容器内访问mongodb://huly.local:27017实际就是访问宿主机上由 start.sh 启动的本地 MongoDB。MONGO_OPTIONS连接池控制不同服务对 MongoDB 连接池的规划不同——transactor 作为核心同步服务使用maxPoolSize: 10而 collaborator、front、print 等轻量服务仅用 12 个连接避免本地开发机上连接数过多。compressorssnappy启用 snappy 压缩传输降低容器与宿主机间的网络数据量。配套基础设施该 compose 还一并启动了 MinIO对象存储端口 9000/9001、Elasticsearch 7.14.2全文检索端口 9200含 ingest-attachment 插件自动安装逻辑以及 rekoni、print、sign、aiBot 等服务——只有 MongoDB 被刻意排除在容器之外这正是本方案的核心设计。另外dev/tool/package.json 中的run-local-mongo脚本同样使用DB_URLmongodb://localhost:27017、ACCOUNT_DB_URLmongodb://localhost:27017指向本地实例可用于在本地数据库上执行upgrade-workspace等维护操作进一步印证本地 MongoDB huly.local是这套开发环境的标准数据后端组合。六、常见问题排查容器连不上数据库connection refused确认已先执行./start.sh本地 mongod 处于监听状态确认huly.local能解析到宿主机对应编排应包含extra_hosts: huly.local:host-gateway查看~/.mongo/mongod.log是否有异常启动记录。数据导入后内容不完整检查 dump 目录是否为空或是否只导出了部分库mongorestore的--drop会先清空目标库若担心误删可去掉--drop后重新导入。端口被占用若27017已被其他 MongoDB 实例占用需要停掉旧实例或修改bindIp/端口配置但要注意 compose 中MONGO_URL的端口需同步修改。想重置开发数据停止本地数据库后清空~/.mongo/data目录内容再./start.sh即可得到一个全新的数据库环境注意此操作不可恢复请先./dump.sh备份。七、小结dev/local-mongo 用一套极简脚本把 Huly 开发环境中最不透明的数据库环节彻底透明化start.sh/stop.sh负责生命周期dump.sh/import.sh负责数据搬运与迁移mongod.conf精确控制存储、缓存与网络行为而docker-compose.yaml通过huly.local主机名把整套容器无缝接到本地实例上。对需要在本地反复重建容器、调试数据、执行迁移或升级脚本的开发者而言这是一条值得优先采用的本地方案。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考