docs: DEPLOY 增加接手人环境差异清单（均可本机自行解决）

说明勿拷贝开发者 .env/feishu.env、常见排障与部署前自检，明确不绑定单机环境。

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -43,6 +43,8 @@ bash scripts/dev_up.sh
 
 `AS_WORKSPACE_ROOT`（DMS 训练大图）**验收送标流程不必配置**；有外部 workspace 时再在 `.env` 填写。
 
+**环境差异说明：** 路径、端口、Docker 权限、前端构建等项因机器而异，但**均可在本机按 [docs/DEPLOY.md §9](docs/DEPLOY.md#9-开发机-vs-接手人环境均可本机自行解决) 自行解决**，不依赖开发者个人目录。
+
 **推送代码到远端：**
 
 ```bash
@@ -320,7 +322,7 @@ git push origin main
 
 | 文档 | 说明 |
 |------|------|
-| [docs/DEPLOY.md](docs/DEPLOY.md) | **新机器部署** |
+| [docs/DEPLOY.md](docs/DEPLOY.md) | **新机器部署**（含 §9 环境差异清单） |
 | [docs/HANDOVER.md](docs/HANDOVER.md) | 架构、API、运维、排障 |
 | [docs/DEVELOPMENT_GUIDE.md](docs/DEVELOPMENT_GUIDE.md) | 开发指南 |
 | [lake/lake_example/README.md](lake/lake_example/README.md) | 数据湖 inbox 示例 |

docs/DEPLOY.md

@@ -192,3 +192,64 @@ docker compose --profile minio up -d
 | 端口冲突 | 修改 `.env` 中 `AS_PLATFORM_PORT`、`CVAT_PORT`、`AS_DB_PORT`、`AS_REDIS_PORT` |
 
 更多架构与 API 说明见 [HANDOVER.md](HANDOVER.md)。
+
+---
+
+## 9. 开发机 vs 接手人环境（均可本机自行解决）
+
+以下条目是 **环境差异**，不是仓库缺陷。每一项都可以在接手人自己的主机上通过配置或一次性命令解决；按 `init_after_clone.sh` → `dev_up.sh` 走，**送标样例流程不依赖开发者的个人目录或数据**。
+
+### 9.1 不要从开发者机器拷贝的文件
+
+| 文件 | 原因 | 接手人做法 |
+|------|------|------------|
+| `.env` | 含开发者绝对路径（如 `/home/xxx/DATA/...`） | 用 `init` 从 `.env.example` 生成，再按本机改路径 |
+| `manifests/feishu.env` | 含飞书 Secret、个人 admin open_id | 用 `feishu.env.example` 复制；验收阶段保持 `AS_DEV_AUTH=true` 即可 |
+
+### 9.2 首次部署常见差异
+
+| 现象 | 原因 | 本机解决 |
+|------|------|----------|
+| 8787 白屏 | `platform/ui-hsap/dist` 不在 Git | 安装 Node 18+ 后 `bash scripts/build_web.sh`（`init` 会尝试） |
+| `docker: permission denied` | 用户不在 `docker` 组 | `sudo usermod -aG docker $USER` 后重新登录 |
+| 样例 DMS 拷不进 inbox | 曾用 root 跑过 Docker，`inbox` 属主为 root | `sudo chown -R $USER datasets/dms/inbox` 后重跑 `seed_lake_example.sh` |
+| 扫描不到 ADAS 批次 | `datasets/adas` 软链或 `data/送标/adas` 未建 | 重跑 `bash scripts/seed_lake_example.sh`；确认 `AS_DATA_LAKE_HOST` |
+| 首次 `up` 很慢 | 需拉 CVAT / ClickHouse 等大镜像 | 保证能访问 Docker Hub，等待拉取完成 |
+| 端口被占用 | 8787 / 8080 / 5433 / 6380 冲突 | 改 `.env` 对应端口后 `docker compose up -d` |
+| CVAT iframe 空白（局域网） | 浏览器用 IP 访问，`.env` 仍是 `127.0.0.1` | 改 `AS_FRONTEND_URL`、`CVAT_PUBLIC_URL` 为实际 `http://<IP>:端口` |
+| 车队地图无瓦片 | 未配高德 Key | 可选：`.env` 填 `AS_AMAP_KEY`；不影响送标主流程 |
+| `git clone` 失败 | 无 git.sanyele.com 权限 | HTTPS + Gitea Token，或登记 SSH 公钥 |
+
+### 9.3 本就不随 Git 带走的内容（新机器为空是正常的）
+
+| 内容 | 说明 |
+|------|------|
+| Docker 卷 `hsap_*` | 用户、标注任务、CVAT 数据；新环境需重新「扫描 → 登记 → 开标」 |
+| `workspace/` 训练大图 | 仅训练需要；`lake_example` 已覆盖送标验收 |
+| 开发者 `data/送标/` 真实批次 | 生产数据各自挂载；样例在 `lake/lake_example/` |
+
+### 9.4 部署前自检（复制执行）
+
+```bash
+docker --version && docker compose version
+node -v && npm -v                    # 建议 Node 18+
+groups | grep -q docker && echo OK   # 或在 docker 组
+
+cd HSAP
+bash scripts/init_after_clone.sh
+bash scripts/dev_up.sh
+make health
+
+# 浏览器：8787 → 开发登录 → 批次台账应能扫到 20260616_adas2d_pilot
+```
+
+### 9.5 可选能力（验收样例不强制）
+
+| 能力 | 何时需要 |
+|------|----------|
+| `AS_WORKSPACE_ROOT` | DMS/Lane 训练、大图 promote |
+| 飞书 OAuth | 关闭 `AS_DEV_AUTH`、走正式登录与任务通知 |
+| `AS_AMAP_KEY` | 车队地图国内底图完整显示 |
+| MinIO profile | S3 暂存联调 |
+
+**结论：** 仓库不绑定某一台开发机；路径、端口、认证、Docker 权限均在接手人本机配置即可跑通。