Logan.Li
5eb11826db
CI / Lint & TypeCheck (push) Canceled after 0s
CI / Test (push) Canceled after 0s
CI / Tauri Foundation Acceptance (push) Canceled after 0s
CI / Build (macos-latest) (push) Canceled after 0s
CI / Build (ubuntu-latest) (push) Canceled after 0s
CI / Build (windows-latest) (push) Canceled after 0s
- apps/server：Gin embed 官网 + /docs + /health + /download（无操作 API） - run.sh 重写 web/gui 场景；.gitignore 排除 server 二进制与挂载的安装包 - README/AGENTS/CLAUDE 同步「浏览器只看官网、操作走桌面」的产品形态说明 - 终端视口背景变量与全宽终端边缘 hairline 修正（serial/terminal/i18n 微调）
94 lines
5.2 KiB
Markdown
94 lines
5.2 KiB
Markdown
# OpsXShell 开发指南
|
||
|
||
轻量运维**桌面**终端（Tauri 2 + Rust + React + TS）。强调短路径好用；**不做**审计、审批、堡垒机。
|
||
|
||
请使用中文沟通。改功能后优先 `npm run test:patrol`。
|
||
|
||
## 产品形态（硬边界）
|
||
|
||
```text
|
||
浏览器 → 只看官网 + 文档（Gin :8789）
|
||
操作 → 只走桌面 Tauri（./run.sh gui）
|
||
Vite :1420 → 仅桌面 WebView 源，不是浏览器产品
|
||
```
|
||
|
||
| 职责 | 放哪 |
|
||
| -------------------------------------------------- | --------------------------------------------------------------- |
|
||
| 桌面操作（SSH/SFTP/转发/RDP/VNC/串口/本地终端/AI） | **本仓** `src/` + `src-tauri/` |
|
||
| 产品官网 + 用户文档 | **本仓** `apps/server`（Gin embed；原 `site-opsxshell` 已并入） |
|
||
| 结账 / 在线授权 | 独立服务 **opsx-licence**；桌面只验 `LIC-` / `LICOFF-` |
|
||
|
||
同族对照：**opsxdb / opsxapi** 同形态（浏览器=官网/docs，操作=桌面）。Shell 的 Gin **只有** site/docs/health/download，**没有**操作 API——原生能力全在 Rust。
|
||
|
||
`src/` 里的 React 是 **Tauri WebView UI**，不是浏览器 SaaS 客户端。
|
||
|
||
### 目录对齐说明
|
||
|
||
- 已对齐：`apps/server`（Gin 官网+docs）、`./run.sh web|gui` 场景。
|
||
- **暂不**把 `src/` / `src-tauri/` 物理迁到 `apps/web` / `apps/desktop`（db/api 的 monorepo 布局）；语义已统一，大挪目录收益小、打断现有打包与 CI。需要时再单独立项。
|
||
|
||
## 架构（怎么改代码）
|
||
|
||
```text
|
||
UI / Zustand → src/platform/* → Tauri command → src-tauri/services/*
|
||
apps/server → Gin：/ 官网 · /docs · /health · /download（无操作面）
|
||
```
|
||
|
||
- `src/platform/`：唯一 `invoke` / 事件入口；组件与 store **不直接** `invoke`。
|
||
- `src-tauri/src/commands/`：参数边界 + 统一响应；业务在 `services/`。
|
||
- `shared/types/`：前后端契约；新能力先契约再 command，再补 `desktop.d.ts` / `platform` / `test/setup.ts`。
|
||
- 文案：`src/i18n` 七语种同步；`test/i18n/localeKeys.test.ts` 校验 key。
|
||
- 官网 HTML：`apps/server/internal/site/`；用户文档 Markdown：`apps/server/internal/docs/content/`（改完重编 server）。
|
||
|
||
扩展顺序：契约 → services → command → platform → UI → 测试。
|
||
|
||
### IPC
|
||
|
||
- 业务失败（SSH/SFTP/转发/会话/本地文件）：信封 `{ success, error, errorCode? }`。
|
||
- RDP/VNC 运行态：throw，视图里 catch。
|
||
- 文件对话框 command 须在主线程；磁盘 I/O 用 `spawn_blocking`。
|
||
|
||
## 硬边界（少而硬）
|
||
|
||
1. 界面不展示 Rust 未实现的能力。
|
||
2. 密码 / 私钥口令 / 代理密码：Rust 加密落盘；主密钥 `~/.opsxshell/master.key`（Unix `0700`/`0600`）。
|
||
3. 不保存终端命令历史；批量结果仅当前窗口。
|
||
4. known_hosts 校验；`ssh://` 禁止带密码或静默直连（走快速连接确认队列）。
|
||
5. 转发：规则可持久化，**运行态不落盘**；停止必须关掉真实 Listener；改运行中规则先停 Listener。
|
||
6. 会话运行态（SSH/转发/RDP/VNC worker）只在原生内存；断开即清理桌面 worker。
|
||
7. 不把结账/签发、CLI/MCP/插件宿主、堡垒机审批做成默认能力。
|
||
8. 不恢复旧 Electron 桌面壳、旧构建链。
|
||
9. **不要**把桌面操作做成浏览器工作台；`:1420` 不是对外入口。
|
||
|
||
## 领域要点（细节跟现有代码，勿另起炉灶）
|
||
|
||
- **隧道**：`TunnelManager` 统一持有/取消；同窗重连可 orphan-adopt / `forwardIntent`；关标签不自动再启。SOCKS5 默认 `127.0.0.1`，每主机一条动态规则。
|
||
- **SSH/SFTP**：协议心跳保链路（勿向 Shell 灌回车空格）；意外断开有限次重连；SFTP 分清 upload/download 与路径方向。
|
||
- **RDP/VNC**：仅桌面端；有限次重连；压缩/帧路径跟 `services/desktop/`，勿新开解压栈。
|
||
- **AI**：新配置先临时凭据实测再落盘；远程执行只复用当前 SSH；critical 硬拒绝。
|
||
- **授权**：只对接 opsx-licence；本地验 `LIC-` / `LICOFF-`。
|
||
|
||
实现时优先对照邻近模块与单测，而不是在本文件追加细则。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
./run.sh # = web：官网 + docs → :8789
|
||
./run.sh web # 同上
|
||
./run.sh gui # 桌面操作入口（默认顺带起 Gin）
|
||
./run.sh stop | status
|
||
npm run test:patrol # 改功能优先
|
||
npm run acceptance:quick # 或 acceptance:full
|
||
./scripts/build.sh # 当前平台安装包 → release/
|
||
./scripts/macos-notarize.sh # 新 DMG 公证（有凭据时）
|
||
```
|
||
|
||
无签名凭据时不要宣称已签名/公证/自动更新。打包须在目标 OS 实机验收。
|
||
|
||
## 给 AI 的协作原则
|
||
|
||
- **先做再问**：需求清楚就直接改；不确定时用最小假设推进，并在回复里写明假设。
|
||
- **跟仓内模式**：新功能对齐现有 `platform` / `services` 分包，禁止平行架构。
|
||
- **少造文档**：非用户要求不要新增长篇 markdown；改行为同步必要注释即可。
|
||
- **测试够用**：功能改动跑 patrol + 相关单测；不必为每个微规则再加一篇规范。
|