GEO 平台接手开发手册
接手团队在现有代码库上继续迭代，沿用现在的服务器与域名，不另起炉灶。本手册讲清四件事：如何拿到访问权限、搭好本地开发环境、把代码提交上去、以及把改动安全地发布到现有线上。
00交接说明
这次不是"另搭一套"，而是在现有系统上接力。先把这三点建立在脑子里，后面就顺了。
全部共用一套。同一个 GitHub 代码库、同一台服务器、同一个域名、同一个数据库。你们接手后是在现有代码上继续改、继续发，线上是同一个正在运营的站点。
你要的是"开发 + 发布"权限，不是"从零部署"。不用买服务器、不用配域名、不用建库。原团队给你开通仓库协作者、服务器部署密钥、以及本地开发要用的密钥文件即可（见第 1 节）。
因为共用生产，协调最重要。同一台线上服务器、同一条代码分支，一次失误会影响正在使用的真实客户。发布前先同步、先打招呼——具体见下面五条铁律。
!!协作五铁律——共用生产的翻车高发区
每一条都对应原团队踩过的一次真实事故。发布前扫一眼，比出事再回来查省事得多。
1发布前必须先 git pull
共用代码库，云端常比你本地新。不先 pull 就发布，会用落后的代码覆盖线上，让已上线功能凭空消失——而且本机怎么测都测不出来。
2只用 deploy-sync.sh 整目录发
常规发布一律走 deploy-sync.sh（整目录同步）。别自己挑几个改动文件传——漏传一个就会拼出新旧混合的代码、线上崩溃重启。
3前端在本机构建
在服务器上跑 vite build 会先清空 dist 再生成，失败即整站白屏。deploy-sync.sh 已按"本机构建、上传替换"设计，照它用就对。
4AUTH_SECRET 绝不改
登录签名密钥一旦改动，线上所有人立即被登出、全体需重新登录。除非明确要求，永远别动 .env 里的它。
5两队动手前先打招呼
同分支、同生产。别两边同时发布。发布前先 --verify-only 看一眼线上状态，确认没人正在发、勤 pull 小步提交，减少冲突。
01需要原团队为你开通的权限
下面四样，是接手团队开工的全部前置。前两样必须有，后两样用于本地开发。
| 要什么 | 必需？ | 用途 / 怎么拿 |
|---|---|---|
| GitHub 仓库协作者 | 必需 | 把你们的 GitHub 账号加为 geo-saas-platform（及采集器 geo-collector）的 Collaborator，才能 clone / push |
| 服务器部署密钥 | 必需 | 免密登录生产机的 SSH 私钥 ~/.ssh/geo_deploy，发布上线（第 4 节）时用。私钥，需安全传递 |
| .env 密钥文件 | 开发需要 | app/.env，含签名密钥、AI/抓取 API Key 等。本地跑起来要用。敏感，需安全传递 |
| 本地开发用数据库 | 二选一 | data/geo.db（含真实客户数据的副本），或起一个空库自建管理员（见 2.3） |
私钥和 .env 走安全渠道交接。用加密压缩包 / 私密渠道传，别丢工作群、别用明文邮件。这些文件已被 git 忽略、不在仓库里，正是因为它们一旦泄露等于账号和服务器失守。
02搭本地开发环境
在开发者自己的电脑上把项目跑起来（Mac / Windows 均可）。先装 Node 22，再拉代码、放密钥、起服务。
2.1 拉代码、装依赖
Node 必须 ≥ 22。平台用了 Node 22 内置的 SQLite，低版本跑不起来。node -v 确认一下。
# 拉平台仓库（首次需登录 GitHub / 输令牌）
git clone https://github.com/frozen-dj/geo-saas-platform.git
# 代码主体在 app/ 子目录，后续都在这里操作
cd geo-saas-platform/app
# 装依赖
npm install2.2 放入密钥与数据
把原团队给你的两个文件放到位（这两个文件不在 git 里，要手动放）：
- 把
.env放到app/.env - 把
geo.db放到app/data/geo.db（若走空库方案则跳过，见 2.3）
2.3 （可选）不想用真实数据？起一个干净的本地库
如果本地开发不想碰真实客户数据，可以不放 geo.db，改用空库并自建一个本地管理员账号——首次启动会自动建好所有表：
# 建库 + 建平台管理员（账号密码取自 .env，幂等可重复跑）
npm run seed:admin2.4 启动开发服务
npm run dev
# 前端跑在 5400，后端接口跑在 4400
# 浏览器打开 http://localhost:5400，用 .env 里的管理员账号登录能登录、看到看板就说明本地环境就绪。改代码会热更新，边改边看效果。本地怎么折腾都不影响线上——线上要等你走第 4 节的发布流程才会变。
03分支与提交代码
就在当前活跃分支上开发，别新建或切换分支——那会让两台电脑、两个团队的代码分叉，后面合并很痛苦。
当前活跃分支是 feat/ops-overview-redesign（最新最全）。clone 下来默认就在它上面，正常无需切换。日常提交推送都作用于当前分支对应的云端，不用指定分支名。
提交并推送的标准流程
# 1) 纳入所有改动
git add -A
# 2) 提交，写人话概括这次改了啥（别加 AI 署名）
git commit -m "修复登录按钮点不动"
# 3) 先合并云端最新，防止和别人打架
git pull --no-edit
# 4) 推到云端
git push第 3 步 git pull 若提示冲突，先停下别硬解——找清楚是哪段代码撞了、和对方确认后再处理。两队都在推同一分支时，勤 pull、小步提交能大幅减少冲突。
04发布到现有生产
仓库里已经有一个把整套流程走完的发布脚本 deploy-sync.sh。它一条命令做完：本机自检 → 本机构建前端 → 整目录同步 server/ 与前端产物到生产机 → 重启后端 → 核验线上真实产物。你不用自己 ssh、不用记服务器地址。
发布要在你自己的终端里跑（脚本要用到第 1 节那把 SSH 部署密钥）。生产机地址已写在仓库的 deploy-target.env 里、脚本自动读取，指向现有的线上服务器，无需改动。
4.1 先看一眼线上现状（不动生产）
发布前先跑只读核验，确认线上是什么状态、有没有别人正在发：
bash app/deploy-sync.sh --verify-only4.2 正式发布
# 记得先 git pull 拿到云端最新（铁律 1）
git pull --no-edit
# 一条命令走完发布全流程
bash app/deploy-sync.sh脚本已内置多重保险：有未提交改动会先让你确认、本机单测不过就中止、前端产物按"临时目录 + 原子替换"上线（没有白屏窗口）、后端起不来会提示回滚。跑到最后打印一串 ✓ 核验项，把带 ❌ 的发原团队对一下即可。
发布完成后，打开线上域名点一点确认改动生效。养成习惯：只认线上真实产物，别只信脚本回显里的"完成"。
05Windows 采集器（在你们那边配置）
采集器是另一个仓库、跑在 Windows 采集机上的独立程序：去各 AI 引擎跑问答、把结果回传现有平台。它可以完全在你们自己的机器上配置，回传到同一套线上平台。
- 在平台生成采集密钥：用平台管理员账号登录现有线上平台，由后台生成一枚采集密钥（形如
col_xxx）——它是采集机回传时的通行证。 - 在采集机拉代码：
git clone https://github.com/frozen-dj/geo-collector.git，进目录npm install、npm run install-browser。 - 配置连接：把采集器指向现有平台的地址、填入上一步的采集密钥和目标租户 ID（在采集器自带控制台界面里填，或写进它的
.env）。 - 现场登录账号：各 AI 引擎账号需在采集机上手动登录一次，登录态存在本机
profiles/目录，不随 git 走。 - 启动采集：按采集器仓库里的《部署到Windows.md》运行。
采集器的详细操作、海外引擎代理配置等，都在它自己仓库的中文文档里（《部署到Windows.md》《海外引擎接入.md》《账号池改造方案.md》等）。这块可等本地开发跑顺后再单独对接。
06常见卡点排查
| 现象 | 多半是因为 | 怎么办 |
|---|---|---|
| clone 报权限错误 / 404 | 还没被加为仓库协作者 | 让原团队把你的 GitHub 账号加成 Collaborator |
| 发布脚本连不上服务器 / 权限被拒 | 没有部署私钥，或没放对位置 | 拿到 ~/.ssh/geo_deploy 放到该路径；确认权限 chmod 600 |
npm run dev 报 SQLite 相关错 | Node 版本低于 22 | node -v 确认 ≥ 22，低了升级 Node |
| 本地登录不进去 / 没数据 | 没放 .env 或没放 geo.db | 放好这两个文件；或用 npm run seed:admin 起空库建号 |
| 发布后线上没变化 | 没先 pull，或只挑了几个文件传 | 先 git pull，一律用 deploy-sync.sh 整目录同步 |
| 线上所有人突然被登出 | 改了 AUTH_SECRET | 把它改回原值即可恢复；今后别再动它 |
git pull 提示冲突 | 和另一台电脑/另一队改了同处 | 停下别硬解，和对方确认后再逐个处理 |