From 7f3b84faf028cabd3ba8184bcda8408f6aa8ce10 Mon Sep 17 00:00:00 2001 From: Chengfang Lu Date: Tue, 16 Jun 2026 17:40:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20DEPLOY=20=E5=A2=9E=E5=8A=A0=E6=8E=A5?= =?UTF-8?q?=E6=89=8B=E4=BA=BA=E7=8E=AF=E5=A2=83=E5=B7=AE=E5=BC=82=E6=B8=85?= =?UTF-8?q?=E5=8D=95=EF=BC=88=E5=9D=87=E5=8F=AF=E6=9C=AC=E6=9C=BA=E8=87=AA?= =?UTF-8?q?=E8=A1=8C=E8=A7=A3=E5=86=B3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 说明勿拷贝开发者 .env/feishu.env、常见排障与部署前自检，明确不绑定单机环境。 Co-authored-by: Cursor --- README.md | 4 +++- docs/DEPLOY.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2c6751c..d23b70b 100644 --- a/README.md +++ b/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 示例 | diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 21a5d4e..2b9e5c7 100644 --- a/docs/DEPLOY.md +++ b/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://:端口` | +| 车队地图无瓦片 | 未配高德 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 权限均在接手人本机配置即可跑通。