从源码到一个能进的 3D 虚拟世界：部署这条路上哪些活要人做
3D 虚拟世界部署、自部署 3D 世界、Node.js 3D 服务器、PostgreSQL 3D 世界、WebSocket 反向代理、Docker 部署 3D、内网 3D 部署、Three.js 自部署、环境变量配置、密钥管理
上一篇把源码的家底摊开了，这篇接着走下一步：从 clone 到一个你自己服务器上、浏览器打开就能进的世界，中间要经过哪些步骤——以及哪些步骤是文档替不了人手的。
先把一个常见的误会说清："下载就能跑"不等于"什么都不用装"。这是一套标准 Node 工程，环境、数据库、配置都要先就位——部署文档会把每一步带着走，但执行的人是你。因为部署耗时因机器、因网络、因人而异，本文不给任何部署耗时数字，也不编一个。
一、部署路径：仓库里为这条路准备的东西
| 步骤 | 仓库里对应的东西 | 说明 |
|---|---|---|
| 1. 检查环境 | check-env.js、环境检测.bat | Node 版本、依赖、数据库驱动齐不齐，先自检再动手 |
| 2. 建库导表 | database/、Database_Import.md、数据库导入.md | 建表脚本与导入说明，PostgreSQL |
| 3. 配置环境变量 | .env.example 等示例文件 | 数据库连接、密钥、端口全部集中在环境变量，示例文件里逐项有注释 |
| 4. 启动 | 启动服务器.bat / 直接 Node | Windows 启动脚本或命令行；也提供 Dockerfile 与 docker-compose.yml |
| 5. 验证 | scripts/ 里的验收脚本 | 54 个 accept_*.js，跑通了比"页面能开"更有底 |
这条路的设计逻辑只有一个：所有会因机器而异的东西，都收进环境变量和配置文件；代码本身不藏环境假设。 这样换一台服务器，改的是配置，不是代码。
二、哪些活文档替不了人做
诚实地说，下面这些只能人来做：
- 装环境本身。Node 装哪个版本、PostgreSQL 怎么装、防火墙端口怎么开——文档写清楚，敲命令的是你。
- 域名与 HTTPS。要公网访问就得有域名，备案、证书、反向代理这些活与代码无关，但与"能不能被访问"直接相关。
- 密钥管理。数据库密码、JWT 密钥、AI 提供商的 Key，示例文件里都是占位符，真实值要你自己生成、自己保管。这里有一条值得抄走的原则：密钥一旦泄露，“删除”不能代替“轮换”——仓库历史、缓存、存档站都可能留有副本，正确顺序是先轮换、再清理。
- 数据备份策略。库表脚本给你了，备份周期和保存策略是你的运营决策。
三、部署完第一眼：能进的世界长什么样
这是部署完成后浏览器里能看到的世界（桌面端实机截图）：玩家角色站在出生点，周围是建筑、动物和告示牌。第一眼看到画面，说明渲染、资源加载、实时通信三条链路都通了。
同一套服务，手机浏览器也能进（实机截图）：虚拟摇杆、语音按钮、拍照与跳跃控件，顶部有登录提示和跨世界入口。如实说明：手机端能进世界有截图为证，但手机端的帧率与耗电我们尚未完成完整实测，性能数字请以你自己的机型实测为准。
四、新手最常卡的三个点
根据我们自己部署和答复咨询的经验，卡点大多不在这套代码，而在环境：
- 数据库连不上。 十有八九是认证配置——PostgreSQL 的认证方式（peer/trust/密码）没对齐，或连接串里的主机端口写错。
check-env.js会先替你拦一道。 - 端口通了但页面打不开。 多半是反向代理没配 WebSocket 升级——这个世界的实时同步走 WebSocket，代理不透传就会出现"页面能开、进不了世界"的现象。
- 改了配置不生效。 环境变量改完要重启进程；用 Docker 跑的话注意容器是否挂载了最新的配置文件。
五、这个部署路线适合什么，不适合什么
- 适合：有自己的服务器（云主机或内网机器）、愿意照文档动手、想要数据在自己手里的人。
- 不适合：完全不想碰服务器的人——这套源码的立场是自部署，没有托管版；这种情况建议等我方提供托管方案或找服务商代部署。
- 中间态：能操作服务器但没时间——仓库文档足够细，也可以把这份文档直接交给你的运维或外包，照单执行。
六、边界与未实测项
- 本文不给部署耗时——机器、网络、熟练度差异太大，编一个数字对你的决策没有帮助。
- 容器路线（Dockerfile / docker-compose）可用，但我们自己的生产环境跑的是非容器部署，容器路线没有经过我们生产环境的长期验证。
- 手机端能进世界有实机截图为证，帧率与耗电未做完整实测。
- 部署文档以仓库当前版本为准，界面与步骤会随版本演进。
常见问题
Q：一定要用 Docker 吗？
A：不用。两条路都在仓库里：直接 Node 跑（我们的生产路线）或容器跑（仓库提供入口）。选你运维上顺手的。
Q：内网能部署吗？
A：可以，这正是自部署的价值之一。渲染在访客浏览器里完成，服务器只发数据，内网部署不需要额外的渲染硬件；去 CDN 化之后依赖全部本地化，离线环境也能跑。
Q：一台什么配置的服务器够用？
A：取决于并发规模，不给万能数字。可以参考的实测锚点：100 个 AI Agent 在线时服务器开销约 0.079 核、每个 Agent 约 1 KB/s；真人在线的开销主要在 WebSocket 消息转发。按你的目标人数倒推即可。
Q：部署完第一步该干什么？
A：跑验收脚本。54 个 accept_*.js 是现成的健康检查，跑通再往里加内容，出了问题也有对照基线。
源码与仓库
三个地址内容一致，国内访问用前两个更快。仓库里有部署说明和一批验收脚本，可以自己跑一遍看实测值。
- Gitee（国内访问更快）：https://gitee.com/miduoxinxijeji/miduo.git
- GitCode（国内镜像）：https://gitcode.com/qq_35054471/virtual-world
- GitHub：https://github.com/miduo100/3d-virtual-world
关于创世Genesis
创世Genesis是一套基于Three.js+WebGL构建的自部署3D虚拟世界系统，帮助个人与企业搭建属于自己的3D空间。浏览器直接访问，PC和手机双端兼容，支持多人在线、联邦传送、商铺系统，并支持Agent接入——AI能以具身角色进入你部署的世界。数据运行在你自己的服务器上，不经过第三方平台——让每个世界都真正属于它的主人。
部署路上卡住了，或者想找人聊聊你的场景？ 创世Genesis（创世虚拟世界CRM系统）是一套部署在你自己服务器上的 Three.js 3D 虚拟世界基底——源码开放、本地跑不花钱，联网、商用、联邦需要订阅授权；部署文档、环境检测、数据库脚本、验收脚本全部在仓库里。官网（搜「创世虚拟世界CRM」即可找到）有一个可以走一圈的演示世界。
关于名字：本文说的创世Genesis，即创世虚拟世界CRM系统，两者是同一个自部署 3D 虚拟世界产品。若你通过「创世Genesis」没搜到我们，直接搜「创世虚拟世界CRM」即可。