From aa2bd804183dddac344d8f26ddc047db0076a4ab Mon Sep 17 00:00:00 2001
From: lipan <lipan@rayqi.com>
Date: Tue, 7 Jul 2026 18:15:53 +0800
Subject: [PATCH] docs: document dev server workflow

---
 docs/开发环境与协作方式.md | 110 +++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/开发环境与协作方式.md

diff --git a/docs/开发环境与协作方式.md b/docs/开发环境与协作方式.md
new file mode 100644
index 0000000..55b393e
--- /dev/null
+++ b/docs/开发环境与协作方式.md
@@ -0,0 +1,110 @@
+# 当前源码与开发环境说明
+
+## 结论
+
+当前最新版本源码不在本地 `massive-cloud-export` 目录中，而是在开发服务器 `2680v4`：
+
+```bash
+ssh 2680v4
+cd /home/lipan/massive-cloud-v3
+```
+
+本地 `massive-cloud-export` 更接近旧版离线导出包或历史交付包，可作为历史留档参考；日常开发、联调和问题排查应以 `2680v4:/home/lipan/massive-cloud-v3` 为准。
+
+## 协作方式
+
+- 当前项目由两名开发人员共同维护。
+- 日常习惯是直接 SSH 到 `2680v4` 上修改代码。
+- 修改目录为 `/home/lipan/massive-cloud-v3`。
+- 该目录是当前实际运行服务挂载的源码目录，代码改动会被开发模式服务读取。
+- 服务器工作区可能存在其他开发人员的未提交改动，修改前应先查看状态，避免覆盖他人工作：
+
+```bash
+git status --short
+```
+
+## 外网调试入口
+
+`http://npsx.i-llusion.cn:3002` 不是正式生产环境地址，而是开发环境的公网穿透访问地址。
+
+访问链路为：
+
+```text
+外网浏览器
+  -> http://npsx.i-llusion.cn:3002
+  -> 内网穿透
+  -> 2680v4:3002
+  -> massive-point-cloud-app-dev
+```
+
+服务器上存在 `npc` 穿透客户端进程，连接到 `47.106.245.28:8024`，用于把 `2680v4` 上的开发服务暴露到公网，方便外网访问和调试。
+
+## 当前运行方式
+
+当前服务使用开发模式 Docker 编排文件运行：
+
+```bash
+cd /home/lipan/massive-cloud-v3
+sudo docker compose -f docker-compose.dev.yml ps
+```
+
+关键运行信息：
+
+- 应用容器：`massive-point-cloud-app-dev`
+- 编排文件：`/home/lipan/massive-cloud-v3/docker-compose.dev.yml`
+- 网络模式：`network_mode: host`
+- 应用端口：`3002`
+- 源码映射：`/home/lipan/massive-cloud-v3:/app`
+- 依赖卷：`pointcloud-app-node-modules-dev:/app/node_modules`
+- 数据目录映射：`/home/lipan/massive-cloud-v3/data:/data`
+- 算法目录映射：`/home/lipan/massive-cloud-v3/alg:/alg:ro`
+
+容器启动后会在 `/app` 中执行：
+
+```bash
+pnpm install && pnpm dev --host 0.0.0.0
+```
+
+因此，开发人员在宿主机 `/home/lipan/massive-cloud-v3` 中修改的源码，会通过 volume 映射进入容器 `/app`，由容器内的 Node/tsx 开发服务运行。
+
+## Docker 权限
+
+`lipan` 用户当前直接访问 Docker daemon 权限不足，管理容器时需要使用 `sudo`：
+
+```bash
+sudo docker ps
+sudo docker logs -f massive-point-cloud-app-dev
+sudo docker compose -f docker-compose.dev.yml ps
+sudo docker compose -f docker-compose.dev.yml restart app
+```
+
+## 常用检查命令
+
+```bash
+# 登录开发服务器
+ssh 2680v4
+
+# 进入当前源码目录
+cd /home/lipan/massive-cloud-v3
+
+# 查看代码状态，注意是否有他人改动
+git status --short
+
+# 查看当前容器
+sudo docker ps
+
+# 查看应用日志
+sudo docker logs -f massive-point-cloud-app-dev
+
+# 查看 3002 端口监听
+sudo ss -lntp sport = :3002
+
+# 查看穿透进程
+pgrep -af "npc|nps|frp"
+```
+
+## 注意事项
+
+- `massive-cloud-export` 不是当前最新开发源码目录，后续维护不要以它为准。
+- 如果需要保留旧版交付材料，可以继续保留 `massive-cloud-export`；如果要清理，应先确认其中截图、部署包说明、历史交付内容是否还需要留档。
+- 直接在服务器改代码时，务必先确认工作区状态，避免覆盖另一名开发人员正在修改的文件。