diff --git a/07-start-frontend.sh b/07-start-frontend.sh
index ee61430..b70840a 100755
--- a/07-start-frontend.sh
+++ b/07-start-frontend.sh
@@ -7,7 +7,7 @@
 #    ./07-start-frontend.sh <project> # 只启动指定项目
 #
 #  项目与端口：
-#    pc          → Electron + Vite   :7777
+#    pc          → Electron + Vite   :7777（无 GUI 时设 PC_WEB_ONLY=1 仅用浏览器 :5173）
 #    meetingh5   → React + Vite      :5188
 #    h5          → Vue + Vite        :3003
 #    cms         → UMI Max           :8001
@@ -82,6 +82,12 @@ declare -A FE_PORT=(
   [build-down]=":8003"
 )
 
+# 无 GUI / 缺 libatk 等：仅启动 Vite，浏览器访问（默认 :5173，可用 VITE_WEB_PORT 覆盖）
+if [[ "${PC_WEB_ONLY:-}" == "1" ]] || [[ "${PC_WEB_ONLY:-}" == "true" ]]; then
+  FE_CMD[pc]="yarn dev:web"
+  FE_PORT[pc]=":5173 (Vite 浏览器，PC_WEB_ONLY)"
+fi
+
 # ── 启动单个前端服务 ──────────────────────────────────────────────────────────
 _start_fe() {
   local name="$1"
diff --git a/README.md b/README.md
index 31d0054..c1642e0 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,39 @@
 
 ---
 
+## GitHub：优先配置 SSH 密钥
+
+克隆仓库、`yarn` / `npm` 安装依赖时，部分包会通过 **SSH**（`git@github.com`）访问 GitHub。**请优先在本机或服务器上配置 GitHub SSH 公钥**，再执行 `setup.sh` 或安装前端依赖；这比仅依赖下文的「HTTPS 重写」更符合日常习惯，也少踩坑。
+
+### 1. 生成密钥（若还没有）
+
+```bash
+ssh-keygen -t ed25519 -C "your_email@example.com"
+# 默认路径 ~/.ssh/id_ed25519，可直接回车；passphrase 可选
+```
+
+### 2. 将公钥添加到 GitHub
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+复制输出 → GitHub 网页：**Settings** → **SSH and GPG keys** → **New SSH key** → 粘贴保存。
+
+### 3. 验证连通
+
+```bash
+ssh -T git@github.com
+```
+
+首次会提示是否信任主机，输入 `yes`；成功会出现 `Hi <username>! ...`。
+
+### 4. 无法使用 SSH 时（备选）
+
+在无 SSH、CI、或不能改 `~/.ssh` 的环境，再使用 **`./deploy-test/00-init-tools.sh`** 里的 Git 配置，把 GitHub 的 SSH 地址重写为 HTTPS（见下文「步骤 0」与「pc 前端 yarn install 失败」）。
+
+---
+
 ## 目录结构
 
 ```
@@ -62,9 +95,11 @@ deploy-test/
 
 在**尚未安装 Go、Node、Docker** 的 Linux 测试服务器上，先执行本脚本再跑 `01-init-env.sh` 及后续步骤。`setup.sh` **不会**自动调用它，需手动执行。
 
+**GitHub 访问**：请先完成上文 **「GitHub：优先配置 SSH 密钥」**；本脚本的 **HTTPS 重写** 是在**不能配 SSH** 时的备选，不是首选。
+
 | 项目 | 说明 |
 |------|------|
-| **作用** | 安装 Go（默认 1.22.5，可用 `GO_VERSION` 覆盖）、配置 GOPROXY（测速选节点）、安装 Node.js LTS、全局安装 pnpm/yarn、安装 Docker、将 GitHub SSH 克隆地址重写为 HTTPS（避免 `pc` 等项目 `yarn install` 因无 SSH 密钥失败） |
+| **作用** | 安装 Go（默认 1.22.5，可用 `GO_VERSION` 覆盖）、配置 GOPROXY（测速选节点）、安装 Node.js LTS、全局安装 pnpm/yarn、安装 Docker；**备选**：将 GitHub SSH 克隆地址重写为 HTTPS（当环境无法使用 SSH 时，减轻 `pc` 等项目 `yarn install` 失败） |
 | **环境变量** | `GO_VERSION`（如 `1.22.5`）、`GO_ARCH`（`amd64` / `arm64`）、`NODE_VERSION`（Node 大版本，默认 `20`） |
 | **权限** | 需要 **root** 或 **sudo**（写入 `/usr/local/go`、`/etc/profile.d/deploy-env.sh` 等） |
 | **系统** | 面向 Ubuntu/Debian（`apt-get`）；脚本内注释说明前置条件 |
@@ -127,7 +162,7 @@ vim .env.deploy-test
 ./deploy-test/07-start-frontend.sh
 ```
 
-> **pc（Electron）依赖安装**：在跑 `06-install-frontend.sh` 前，裸机请先执行 **`00-init-tools.sh`**（见上文「步骤 0」，含 GitHub SSH→HTTPS 重写）。仍报错见下文「pc 前端 yarn install 失败」。`pc` 建议仅用 **Yarn**；可删除 `package-lock.json` 消除混用锁文件警告。
+> **pc（Electron）依赖安装**：**优先**按上文配置 **GitHub SSH 密钥**；裸机还需 **`00-init-tools.sh`**（见「步骤 0」）。若仍无法用 SSH，再依赖脚本内的 GitHub **HTTPS 重写**。详见「pc 前端 yarn install 失败」。`pc` 建议仅用 **Yarn**；可删除 `package-lock.json` 消除混用锁文件警告。
 
 > **`07-start-frontend.sh`**：启动前会读取 `.env.deploy-test`（若存在），文末「访问地址」等处使用 `DEPLOY_TEST_IP`；未设置时默认为 `127.0.0.1`，避免脚本在 `set -u` 下因未定义变量退出。
 
@@ -342,8 +377,9 @@ TENCENT_SDK_SECRET_KEY=xxx
 
 | 说明 | 处理 |
 |------|------|
+| **优先** | 按上文 **「GitHub：优先配置 SSH 密钥」** 完成 `ssh-keygen`、公钥添加到 GitHub、`ssh -T git@github.com` 验证通过后再装依赖。 |
 | **锁文件** | 仓库中 `pc/yarn.lock`、`pc/package-lock.json` 已将 `@electron/node-gyp` 的 `resolved` 固定为 **`git+https://github.com/electron/node-gyp.git#...`**（无需 SSH）。请拉取最新代码后再执行 `yarn install`。 |
-| **环境** | 首次部署请执行 `./deploy-test/00-init-tools.sh`，脚本内会通过 `git config url.*.insteadOf` 将 `git+ssh://`、`ssh://git@github.com/`、`git@github.com:` 重写为 `https://github.com/`。 |
+| **备选（无 SSH 环境）** | 首次部署请执行 `./deploy-test/00-init-tools.sh`，脚本内会通过 `git config url.*.insteadOf` 将 `git+ssh://`、`ssh://git@github.com/`、`git@github.com:` 重写为 `https://github.com/`。 |
 | **仍失败** | 手动执行（与 `00-init-tools.sh` 一致）：<br>`git config --global url."https://github.com/".insteadOf "git+ssh://git@github.com/"`<br>`git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"`<br>`git config --global url."https://github.com/".insteadOf "git@github.com:"` |
 | **包管理器** | `pc` 使用 **Yarn**。若同时存在 `package-lock.json`，Yarn 会警告混用锁文件；可删除 `pc/package-lock.json`，仅保留 `yarn.lock`（与团队约定一致即可）。 |