# agent.md — Graw 项目指引 本文件为 AI 编码助手（以及新加入的人类开发者）提供 Graw 代码库的结构、约定与常见陷阱速查。 改动代码前请先通读本文件，确保改动符合既有架构与安全约束。 项目内技能放在 `agent/skills/`（`hop`：面向人类编程的代码规范；`secreview`：安全审查），可读取其中的 `SKILL.md`。 ## 0. 后端更新策略（2026-10 起，重要） - **今后版本更新默认只修改 Go 后端 `backend-go/`**：新增功能、接口变更、缺陷修复、安全加固全部落在 Go 侧。 - **Python 旧版 `backend/` 已冻结**：不再跟随版本更新，不新增功能、不补新接口、不修业务缺陷；仅在确有必要时作为「历史实现参考 / 缺失代码的补充」查阅或复制逻辑。 - 新增接口只需要在 `backend-go/internal/graw/` 实现并在 `httpx.go` 的 `NewApp()` 注册，**不要**为了「保持两版一致」再写一遍 Python 路由。 - `backend/` 仅保留用于：对照旧版行为、运行既有 `pytest` 回归用例、排查历史数据格式；其 `APP_VERSION` 与接口清单不再随版本强制同步。 - 文档、接口说明、前端默认以 Go 实现为准；涉及 Python 的描述统一标注「旧版 / 仅供参考」。 --- ## 1. 项目简介 **Graw** 是一个基于 Web 的服务器管理面板，采用「类桌面操作系统」的交互设计（窗口、任务栏、桌面快捷方式）。 它不仅能管理本机，还支持通过 **Agent 隧道 + 成对访问密钥** 把其它主机作为「子节点」纳入统一面板管理。 核心能力：实时系统监控、Docker 管理、网站（Nginx/OpenResty）管理、数据库管理、计划任务、防火墙、SSL、 日志、文件管理、Web 终端、应用商店、备份、通知中心、防篡改、WAF、多节点/SSH 密钥、内网穿透（Frp）、 插件开放协议（GPOP）、批量操作、SSH 端口转发、每日巡检报告、站点 Git 自动部署、镜像漏洞扫描、慢查询分析等。 界面有两套壳（同一套功能）：类桌面（窗口/任务栏，默认）与 **标准面板模式**（1Panel 风格侧边栏 + 多标签，`settings.panelMode` 切换）； 界面文案支持 **22 个语言包**（`frontend/src/locales/`）。 - 当前版本：Go 后端 `backend-go/internal/graw/cfg.go` 的 `AppVersion = "1.8.1"`（版本号只在 Go 侧维护；Python 旧版 `backend/app/main.py` 的 `APP_VERSION` 不再同步） - 许可证：AGPLv3 - Docker 镜像命名空间：`shunx/graw` --- ## 2. 技术栈 | 层级 | 技术 | |------|------| | 前端 | Vue 3（Composition API）、Vite 5、Axios、ECharts / vue-echarts、xterm.js、vue-i18n | | 后端 | **Go 1.23（默认且唯一持续维护，`backend-go/`）**：标准库 HTTP、gorilla/websocket、gopsutil、JWT；Python 3.11 / FastAPI / Uvicorn 旧版已冻结在 `backend/`，仅作参考与缺失代码补充 | | 通信 | REST API（`/api/*`）+ WebSocket（监控流、终端） | | 部署 | 多阶段 Docker 构建（前端 Node 构建 → Go 交叉编译 → Alpine 运行时） | 依赖清单：`backend-go/go.mod`（默认）、`backend/requirements.txt`（Python 旧版）、`frontend/package.json`。 --- ## 3. 目录结构（关键部分） ``` Graw/ ├── backend/ # Python/FastAPI 旧版后端（已冻结，仅参考/回归测试，不再更新） │ ├── app/ │ │ ├── main.py # 应用入口：路由注册、中间件、lifespan 后台任务、静态托管 │ │ ├── auth.py # JWT 鉴权依赖：get_current_user / require_admin / seed_default_users │ │ ├── agent_auth.py # 子节点 Agent 机器间鉴权（/api/agent，成对密钥换 JWT） │ │ ├── agent_cfg.py # 子节点「收取模式」持久化配置（data/agent.json） │ │ ├── agent_client.py # 主面板 → 子节点的 Agent 隧道代理客户端 │ │ ├── node_manager.py # 多节点管理：当前节点上下文、请求级 X-Graw-Node 覆盖 │ │ ├── remote_cap.py # 远端子节点能力门控（local-only 接口防护） │ │ ├── hostfs.py # 宿主机文件系统适配层（chroot /host 读写宿主文件/命令） │ │ ├── reporting.py # 每日巡检报告（08:00 生成 + 推送，data/reports/） │ │ ├── portforward.py # SSH 端口转发隧道（本地 127.0.0.1 监听，data/portforwards.json） │ │ ├── plugin_protocol.py # 插件开放协议核心（清单校验/令牌哈希/注册表/插件配置） │ │ ├── trash.py # 回收站核心逻辑（跨节点，data/recycle.json） │ │ ├── routers/ # 各业务模块路由（见下方清单） │ │ └── data/ # 运行时数据（用户、密钥、节点凭据等，gitignore，权限收紧） │ ├── test_*_unit.py / test_*_e2e.py # pytest 单测与端到端用例 │ ├── reset_password.py # 离线重置管理员密码脚本（读 data/users.json） │ └── requirements.txt ├── backend-go/ # Go 后端（默认；接口/数据兼容 Python 旧版） │ ├── main.go # 进程入口：配置/播种账号/后台协程/HTTP 服务 │ ├── internal/graw/ # 单包实现：路由、鉴权、SSH/Agent、中间件、各业务模块 │ ├── go.mod / go.sum │ └── Dockerfile # 前端构建 + Go 编译 + 精简运行时 ├── frontend/ │ ├── src/ │ │ ├── main.js # 入口：createApp().use(i18n) │ │ ├── App.vue # 桌面环境根组件 │ │ ├── components/ # Desktop / Taskbar / WinWindow / 各类卡片 │ │ ├── components/windows/ # 每个功能的独立「窗口」组件（*Window.vue） │ │ ├── store/ # 自定义 reactive 状态（auth/systemMetrics/docker/siteBus…） │ │ ├── locales/ # vue-i18n 多语言（zh-TW/ja/ko/ru/de/fr/es/pt/eo…） │ │ └── assets/style.css │ ├── index.html │ ├── vite.config.js # 开发代理 /api(含 ws) → http://localhost:8000 │ └── package.json ├── app-store/ # 社区应用商店的 YAML 配方与图标（安装即 docker compose） ├── plugin-examples/hello-graw/ # 插件开放协议（GPOP）示例插件 ├── docs/ # 开发者/运维文档（部署、子节点 Agent、API 概览、插件协议…） ├── GETMEREAD/ # 「大白话 + Mermaid」运行逻辑文档（11 篇） ├── readme-i18n/ # 多语言 README（10 个语种） ├── agent/skills/ # 项目内技能（hop / secreview） ├── Dockerfile # 多阶段构建（前端构建 → Go 交叉编译 → Alpine 运行时） ├── docker-compose.yml # 「完整管理宿主机」高权限编排 ├── start.sh / start.bat # 本地开发一键启动（Go 后端 + 前端） ├── AGENTS.md # 本文件：架构、约定与陷阱（改代码前必读） ├── CHANGELOG.md / SECURITY.md / CONTRIBUTING.md └── README.md ``` ### 后端路由清单（Go 默认：`backend-go/internal/graw/handlers_*.go`；Python 旧版：`backend/app/routers/`） | 前缀 | 模块 | 鉴权 | |------|------|------| | `/api/auth` | 登录/当前用户/改密/用户管理/OAuth2.0（`/oauth/status|start|callback|exchange|config`） | 登录/管理员（公开登录与 OAuth 回调；配置需完整管理员） | | `/api/agent` | 子节点 Agent 机器间鉴权（`/issue` 换 JWT、`/cfg` 收取模式配置） | 成对密钥（`/cfg` 内部要求管理员） | | `/api/system` | CPU/内存/磁盘/网络/负载 + WS 实时流 | 端点内自行鉴权（WS 用 `?token=`） | | `/api/notes` | 备忘录 CRUD | PROTECTED（登录即可；写操作为管理员） | | `/api/docker` `/api/dockervolumes` `/api/containeredit` | Docker 容器/镜像/卷/编辑 | ADMIN | | `/api/process` `/api/disks` `/api/files` `/api/recycle` | 进程 / 磁盘 / 文件管理 / 回收站 | ADMIN | | `/api/terminal` | WebSocket 终端（paramiko） | 处理函数内 `?token=` + 强制管理员 | | `/api/sites` `/api/sitesopts` `/api/rewrite` `/api/waf` `/api/webmode` `/api/webstats` | 网站/站点增强/伪静态/WAF/引擎模式/访问统计 | ADMIN | | `/api/databases` | MySQL/MariaDB/Redis/PostgreSQL/MongoDB 连接与查询 | ADMIN | | `/api/cron` `/api/firewall` `/api/protection` `/api/ssl` `/api/logs` `/api/backup` | 计划任务/防火墙/防护中心/证书/日志/备份 | ADMIN | | `/api/shunx` `/api/tamper` | ShunX 安全入口 / 网页防篡改（含 WS 告警） | 端点内自行鉴权 | | `/api/appstore` `/api/tasks` `/api/runtime` | 应用商店 / 任务中心 / 运行时容器（应用图标路由公开） | ADMIN（图标公开） | | `/api/plugins` `/api/op` | 应用接口开放协议：插件管理（ADMIN，按 enabled 条件注册）/ 插件开放接口（端点内令牌鉴权）。`/api/plugins/settings` 总开关始终注册 | ADMIN / 令牌 | | `/api/nodes` `/api/sshkeys` | 多节点管理 / SSH 密钥部署 | ADMIN | | `/api/ui` | 界面设置（公开/public + 管理员/config） | 端点内自行鉴权 | | `/api/frp` `/api/netstorage` `/api/update` `/api/notify` `/api/uptime` `/api/certcheck` | 内网穿透/网络储存/更新/通知/可用性/证书 | ADMIN | | `/api/vpn` | VPN 转发策略（Clash 订阅 / mihomo/clash 核心托管 / 低占用看门狗） | PERM("vpn")（订阅端点 `/api/vpn/sub` 以令牌自鉴权，不挂登录依赖） | | `/api/batch` `/api/gitdeploy` `/api/portforward` | 批量操作中心 / 站点 Git 自动部署 / SSH 端口转发（**三者永不经 Agent 代理**） | ADMIN（gitdeploy webhook 端点内验签） | | `/api/report` `/api/rollback` `/api/imgsafety` `/api/slowquery` | 巡检报告 / 配置快照回滚 / 镜像漏洞扫描 / 慢查询分析 | ADMIN | | `/api/svcmonitor` `/api/healthcheck` | 服务与端口监控 / 一键体检 | ADMIN | | `/api/ftpusers` `/api/toolbox` `/api/phpversions` `/api/panelbackup` `/api/loginlog` | FTP 用户/工具箱/PHP 版本/面板备份/登录日志 | ADMIN（loginlog 为 PROTECTED，管理接口内部再验管理员） | | `/api/health` | 公开健康检查（版本号） | 公开 | > 除 `/api/auth/login`、`/api/health` 外，所有接口均需 `Authorization: Bearer `； > WebSocket 与少数公开/机器间端点（system/terminal/tamper/shunx/ui/agent/appstore 图标/gitdeploy webhook/op）**不挂全局依赖**，在端点内部自行鉴权。 --- ## 4. 环境要求与快速开始 ### 环境要求 - Go 1.23+（默认后端；生产镜像基于 Alpine 静态二进制） - Node.js 16+（前端）；Docker 引擎（Docker 管理功能可选） - Python 3.11（仅运行 `backend/` 旧版或跑 pytest 时需要） ### 本地开发（前后端分离） ```bash # 后端（Go 默认） cd backend-go go mod download go run . # 默认 :8000，可用 GRAW_ADDR 覆盖（如 :8001） # 前端（另开终端） cd frontend npm install # 或 pnpm install npm run dev # → http://localhost:5173，Vite 代理 /api 到 :8000 ``` `backend/` 为 Python/FastAPI 旧版后端，接口路径、请求/响应结构与数据文件格式与 Go 版保持兼容； Go 后端默认复用 `backend/data`（可用 `GRAW_DATA_DIR` 覆盖），前端无需改动。如需运行旧版： `cd backend && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`。 依赖：`docker`/`podman` CLI（Docker 模块）、`certbot`、`crontab`、`smbclient`/`mc` （可选，按功能使用）；容器镜像见根 `Dockerfile` 或 `backend-go/Dockerfile`。 ### 生产构建 / 部署 ```bash cd frontend && npm run build # 输出 frontend/dist # Go 后端会自动检测并挂载 frontend/dist 作为静态资源（SPA 回退到 index.html） cd ../backend-go CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o graw-go . ./graw-go # 默认监听 :8000 # 随后访问 http://localhost:8000 即完整应用 ``` 也可用仓库根脚本 `./graw.sh start` / `graw.bat start` 一键构建并后台运行。 容器化部署见 `docker-compose.yml`（**高权限**，见第 7 节陷阱）。 ### 默认账号 首次启动在 `backend/data/users.json` 自动播种： - 账号 `admin` / 密码 `admin123`，首次登录强制改密。 - 签名密钥持久化于 `backend/data/secret.key`（首次自动生成）。 - 忘记密码可用 `cd backend-go && go run ./cmd/reset-password admin` 离线重置 （实现见 `internal/graw/reset_password.go` 与 `internal/resetpw/`）；Python 旧版为 `cd backend && python reset_password.py admin`。 --- ## 5. 后端开发约定 ### 5.1 路由注册与鉴权模型 - **Go 默认后端**：路由与中间件在 `backend-go/internal/graw/httpx.go` 的 `NewApp()` 注册，业务实现在 `handlers_*.go`、鉴权在 `auth.go`/`sessions.go`。**新增模块必须在 `NewApp()` 注册**，否则前端无法访问。 - **Python 旧版（已冻结）**：所有业务路由集中在 `backend/app/main.py` 用 `app.include_router(..., prefix="/api/xxx")`。**新增模块不要在此注册**（Python 不再跟随版本更新）；以下分级约定仅描述 Go 侧，Python 实现只作历史对照。 - 鉴权分级（定义在 `main.py` 顶部）： - `PROTECTED = [Depends(get_current_user), Depends(require_non_default_password)]` —— 仅需登录（只读信息类）。 - `ADMIN = [Depends(require_admin)]` —— 完整管理员（面板自身安全边界：多节点/SSH 密钥/插件/更新/面板备份/用户管理）。 - `PERM("模块") = [Depends(require_perm("模块"))]` —— 模块级权限（受限管理员按 `users.json` 的 `perms` 白名单收窄；完整管理员全量放行）。**新增业务管理路由默认用 `PERM(...)`**，只有面板自身安全边界才用 `ADMIN`（登记进 `main._FULL_ADMIN_PREFIXES`，否则启动期自检会打 warning）。 - 部分路由**必须**在端点内部自行鉴权、不要挂全局依赖：`system`/`terminal`（WS 用 `?token=`）、`tamper`、`shunx`（/status 公开）、`ui`（/public 公开）、`agent`（机器间密钥）、`appstore` 的图标路由、`gitdeploy` 的 webhook、`op`（插件令牌）。 - `require_admin` 已级联 `require_non_default_password` + `get_current_user`，无需重复声明；`require_perm` 同样级联（非管理员一律 403）。 - **模块权限三处保持一致**：`auth.MODULES`（key 唯一来源）→ `main.py` 路由的 `PERM("模块")` → 前端 `App.vue` 快捷方式的 `perm` 字段（前端只是体验层门控，边界永远在后端）。**前端约定：不按模块隐藏入口**——受限管理员可见全部入口，点开无权限模块仅提示「该用户无此权限」且不打开窗口（`fullAdminOnly` 的面板自身功能除外）。WS 端点用 `require_perm_ws("模块")`；Agent 代理的等价判定由 `main._proxy_perm_map()` 从路由依赖自动汇总，**新路由只要挂对 `PERM(...)` 就自动生效**，无需另行登记。注意：FastAPI ≥ 0.141 起 `include_router` 只登记 `_IncludedRouter` 包装，直接遍历 `app.routes` 拿不到前缀与依赖（映射会静默变空），因此汇总统一走 `main._iter_effective_api_routes()`（内部用官方 `iter_route_contexts()` 展开，旧版本自动回退直读）。 - **必须保留一个完整权限的超级管理员**：用户管理接口（改角色 / 收窄 `perms` / 删除账号）通过 `routers/auth._super_admin_count()` 校验，禁止把「最后一个 `role=admin` 且 `perms` 为空」的账号改没（受限管理员不计入兜底）。新增涉及管理员角色 / 权限的写操作时请沿用该约束。 - **local-only 标记**：新增面板自身管理类接口时，同步在 `remote_cap.LOCAL_PREFIX` 登记，否则它在裸 SSH 远端节点上会被放行到没有意义的本机数据上。 ### 5.2 数据持久化 - 面板所有配置/凭据以 **JSON 文件** 存于 `backend/data/`（如 `users.json`、`nodes.json`、`databases.json`、`agent.json`、`ftp_users.json`）。 - 该目录含敏感信息（SSH 凭据、数据库密码、JWT 密钥）。启动时 Go 的 `SecureDataDir()` / Python 的 `_secure_data_dir()` 在 Linux 上收紧为 `0700`/`0600`，**不要**在代码里放宽其权限。 - 写入配置时优先采用「原子写」：写临时文件后原子替换（Go `os.Rename()` / Python `os.replace()`）。 ### 5.3 多节点 / Agent 架构（重点） - **Go 默认后端**：Agent 鉴权、隧道代理、节点上下文与远端能力门控集中在 `backend-go/internal/graw/agent.go`；业务请求代理中间件在 `httpx.go`。 - **Python 旧版**实现（下述文件仅用于对照）： - **主面板 ↔ 子节点** 通过 Agent 隧道通信： - `agent_auth.py`：`/api/agent/issue` 用成对 `key+secret` 换取子节点 JWT（不依赖面板登录）。 - `agent_cfg.py`：子节点「收取模式」持久化（`data/agent.json`），支持设置界面热开关，无需重启/改环境变量。 - `agent_client.py`：`agent_proxy()` 把请求经隧道转发到子节点；`agent_ready()` 判断可用性。 - `node_manager.py`：维护「当前管理节点」上下文；支持请求级 `X-Graw-Node` 头覆盖（统一面板按窗口聚焦节点下发）。 - `remote_cap.py`：把某些接口标记为 local-only，防止远端子节点越权调用。 - 请求流向（`main.py` 中间件，由外到内；`main.py` 里**最后注册的最先执行**）： 1. `_RequestBodyLimitMiddleware`（最外层）：请求体大小限制——`Transfer-Encoding` 411、`Content-Length` 超限 413（普通 16MB / multipart 2GB，可用 `GRAW_MAX_BODY_MB`/`GRAW_MAX_UPLOAD_MB` 覆盖）、多个不一致 `Content-Length` 400。 2. `agent_proxy_middleware`：当前节点为远程且已配 Agent 时，业务 HTTP 请求优先经隧道代理到子节点（WebSocket 升级不代理），代理前先在本机做与业务路由等价的鉴权。 3. `remote_capability_guard`：local-only 接口门控（纵深防御；远端配了 Agent 时请求已在上一层被代理走，不会到这里）。 4. `security_headers` / `CORSMiddleware`：安全响应头与同源策略。 5. 业务路由 + 鉴权依赖。 - **新增业务接口若需对子节点透传**，确认它不在 `_AGENT_PROXY_EXCLUDE_PREFIX`（auth/nodes/terminal/agent/ui/shunx/health/batch/gitdeploy/portforward/vpn）中即可自动被代理，无需额外改动。 ### 5.4 后台任务 - **Go 默认后端**：后台任务在 `backend-go/main.go` 中成组启动（`StartMetricsBackground`、`StartTrashAutoPurge`、`StartDailyReport`、`StartMonitors`、`StartTamperMonitor`、`RestorePortForwards`、`RestoreVPN`），关闭时由进程退出统一回收；新增常驻监控需在此登记。 - **Python 旧版**：在 `lifespan()` 中启停的 7 个常驻协程：系统指标采集（`system.start_metrics_producer`）、防篡改监控、通知中心、站点可用性、证书到期、服务/端口监控、回收站过期清理（`trash.start_auto_purge`）。另有每日巡检报告协程（`reporting.start_daily`，08:00 生成并推送）、启动时恢复的 SSH 端口转发隧道（`portforward.restore_all`），以及 VPN 转发策略的核心恢复与低占用看门狗（`vpn_policy.restore()` + `start_monitor()`，空闲自动停核心、初次请求唤醒）。**新增常驻监控请在此配对启停**，避免泄漏协程。 ### 5.5 安全中间件 - **Go 默认后端**：请求体限制、远端能力门控、安全响应头等中间件在 `backend-go/internal/graw/httpx.go` 中按顺序包装。 - **Python 旧版**的 `security_headers` 给所有响应附加 CSP / `X-Content-Type-Options: nosniff` / `X-Frame-Options: DENY` / `Referrer-Policy: same-origin`。改动前端注入资源（如新 CDN）时需注意 CSP 限制（`script-src` 已放行 `unsafe-inline` + `unsafe-eval`）。 - 请求体大小限制见 5.3；未认证的大 body 在进业务前就被拒，新增「接收上传」的端点时注意 `multipart/` 与非 multipart 走的是两档限额。 --- ## 6. 前端开发约定 ### 6.1 状态管理（无 Pinia） - 状态使用**自定义 `reactive` 单例**，位于 `src/store/*.js`（如 `auth.js` 导出 `reactive` 的 `auth`，含 `setAuth/clearAuth/isAdmin`）。**不要引入 Pinia**，沿用该模式：新增全局状态就新建一个 `store/xxx.js` 导出 `reactive` 对象。 ### 6.2 双界面形态与窗口系统 - `App.vue` 是根组件，按 `settings.panelMode` 二选一渲染：**桌面模式**（`Desktop.vue` + `Taskbar.vue` + `WindowFrame.vue`）或**标准面板模式**（`PanelLayout.vue`：顶栏 + 分组侧边栏 + 可选标签栏 + 内容区）。 - 每个功能是一个**独立窗口组件** `src/components/windows/*Window.vue`，支持拖拽、最大化/最小化。新增功能页应新建对应 `*Window.vue`，在 `App.vue` 的 shortcuts 里注册入口（`DESKTOP_SC_DEFS` 等展示名映射需同步）。 - 两种壳共用 `WindowContent.vue` 渲染内容；面板模式下约 50 个 `openXxx` 事件经 `inheritAttrs:false` + `$attrs` 透传，**新增窗口事件时两条链路都要照顾**。 - 全局搜索 `CommandPalette.vue`（Ctrl/⌘+K）的入口来自 `visibleShortcuts`，选中后统一走 `openWindow()`（内含 adminOnly 与远端 local 类守卫）。 ### 6.3 API 调用 - 统一经 `src/api.js`（或各 store 内的 axios 封装）调用 `/api/*`，请求拦截器注入 `Authorization: Bearer `（token 来自 `store/auth`）。 - 开发期 Vite 代理（`vite.config.js`）把 `/api` 与 WebSocket 转发到 `http://localhost:8000`；**生产无跨域**（前端由后端同源托管）。 ### 6.4 国际化 - 使用 `vue-i18n`，语种文件在 `src/locales/`（当前 **22 个语言包**，zh-CN 为源语言与 `fallbackLocale`）。 - 新增界面文案应走 i18n key，**不要硬编码中文到模板**；语言清单、locale 兜底与古语言「括号注释」样式统一在 `src/locales/index.js` 维护（`LANGUAGES` / `normalizeLocale` / `applyBracketStyle`）。 - 改完注意跑 `frontend/scripts/check-i18n-keys.mjs` 与 `check-imports.mjs`（漏 key 或漏 import 会导致界面白屏/显示 key）。 --- ## 7. 关键约定与陷阱（务必注意） 1. **API 文档默认关闭**：Go 后端不提供 `/docs`、`/redoc`、`/openapi.json`；Python 旧版默认关闭，调试时设 `GRAW_ENABLE_DOCS=1`。 2. **CORS 关闭**：同源部署，不开放跨域。不要为「方便本地联调」改成 `*`，这会暴露攻击面。 3. **WebSocket 鉴权用 `?token=`**：终端（`/api/terminal`）和监控 WS 无法在浏览器里带 Bearer 头，处理函数内用查询参数 token 鉴权并强制管理员。改动 WS 端点时保持此方式。 4. **`data/` 权限与凭据**：含 SSH/数据库/JWT 密钥，勿提交到仓库、勿放宽权限、勿明文回传前端（`agent_cfg.public_status()` 已脱敏，照此模式）。 5. **容器高权限（仅可信环境）**：`docker-compose.yml` 使用 `privileged` + `network_mode: host` + `pid: host` + `-v /:/host:rslave` + docker.sock。目的是让面板完整管理宿主机；**Docker Desktop for Windows 上这些无法完整生效**。开发阶段建议本地直接跑前后端，而非依赖该 compose。 6. **前端构建产物由后端托管**：`npm run build` 输出 `frontend/dist`，Go 的 `registerStatic`（`httpx.go`）自动挂载 `/assets` 与 SPA 回退。改了前端后若生产不生效，先确认 `frontend/dist` 已生成。 7. **版本号单一来源**：升级版本改 `backend-go/internal/graw/cfg.go` 的 `AppVersion`；Python 旧版对应 `backend/app/main.py` 的 `APP_VERSION`，两处需同步。`/api/health` 在容器部署时优先读镜像 tag/label。 8. **不要绕过远端能力门控 / Agent 代理**：设计新接口时明确它是 local-only 还是需要子节点透传，避免越权或代理失效。`batch` / `gitdeploy` / `portforward` 三类**永远留在主面板执行**，别把它们改成可代理。 9. **请求体大小受限**：全局中间件对 `Transfer-Encoding` 返回 411、超限返回 413（普通 16MB / multipart 2GB）。新增接收大负载的端点时不能用 chunked 上传，必要时改环境变量而不是改代码常量。 10. **文档要跟着改**：功能变更后同步更新 `docs/`（面向开发者/运维）与 `GETMEREAD/`（大白话运行逻辑，规矩见 `GETMEREAD/README.md`：在对应模块文件里追加一节并刷新文字与图，别新建同名文件）。 --- ## 8. 代码风格 - **Go 后端（默认）**：错误显式返回、注释用中文描述背景与安全约束；日志用 `log.Printf`；敏感操作前做鉴权断言。 - **Python 旧版（冻结，不再新增代码）**：仅维护既有代码可读性；类型注解 + Pydantic 模型；日志用 `logging.getLogger("graw.xxx")`。 - **前端**：`