# opsConn

**Repository Path**: willionjake_admin/ops-conn

## Basic Information

- **Project Name**: opsConn
- **Description**: 绿色运维工具，轻量级别的，可以连接数据库mysql、PG、CK，ETCD，REDIS，MSSQL，ORACLE，KAFKa，可以sh 连上Linux服务器，支持VNt,ssh,可以连接交换机，com口; 一个工具解决运维、开发兄弟困境，支持连上sh，可以自动识别连上管理该设备上的数据库（CK、ETCD、REDIS、PG、MYSQL等）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpsConn

OpsConn 是面向运维、研发与数据库管理员的轻量级连接工作台。目标产品采用 Wails 独立桌面窗口、纯 Go Core 与内嵌 Vue；当前仓库已完成第一阶段 Core、安全回环恢复网关、本地元数据、加密凭据保险箱及统一资源治理骨架，Wails 壳迁移尚未实施。

> 当前阶段是可运行的工程骨架，不代表 MySQL、PostgreSQL、ClickHouse、Redis、Kafka、SSH/SFTP 等业务连接器已经交付。连接器将以独立适配器逐步接入现有边界。

## 架构基线

- 正式 UI：Wails + 系统 WebView + 内嵌 Vue，独立 OpsConn 窗口；不携带 Chromium、不打开默认浏览器、不监听 UI TCP 端口。
- Core：Application、Domain、Runtime 和默认 Connector 保持 `CGO_ENABLED=0`；Wails 平台壳依赖限定在 Desktop Adapter。
- Recovery UI：只有用户显式启用才绑定 `127.0.0.1:0`；固定诊断端口冲突自动回退随机端口，且不自动打开浏览器。
- Sidecar：首版默认数量为 0；只有独立 ADR 批准、随包签名且由 Supervisor 托管的能力可按需启动。
- 存储：`modernc.org/sqlite` 提供纯 Go SQLite 元数据库，启动时执行带校验和的迁移和 `quick_check`。
- 凭据：Argon2id + XChaCha20-Poly1305 加密文件保险箱；核心域只传递 `SecretRef`。
- 稳定性：统一 Supervisor 托管协程并恢复 panic，Governor 设置并发硬上限，EventBroker 使用有界队列并主动断开慢消费者。
- 连接器契约：统一 `ConnectionConfig`、`DialRoute`、Capability、Session 和不可变 Registry；业务连接器不得直接拨号或携带明文凭据。
- 可观测性：结构化 JSON 日志、关联 ID、敏感字段递归脱敏、10 MiB × 4 个日志文件的磁盘上限。
- 编码与语言：纯 Go 流式 TextCodec 支持 UTF-8/UTF-16/GBK/GB18030/Big5 等，中文/英文及默认编码可实时切换、持久化并跨窗口同步。

当前架构决策见 [ADR-006](docs/05-decisions/ADR-006-desktop-wails-shell-and-recovery-ui.md)，代码约束见 [AGENTS.md](AGENTS.md)。

## 目录

```text
cmd/opsconn/                  进程入口，只负责信号和退出码
internal/bootstrap/           组合根、启动与有序关闭
internal/apperr/              稳定错误码与错误分类
internal/runtime/             Supervisor、Governor、EventBroker
internal/connectors/          Connector Registry 与工厂 panic 边界
internal/domain/connection/   连接配置、路由、能力和会话契约
internal/infrastructure/      SQLite MetaStore 与迁移
internal/security/vault/      加密凭据保险箱
internal/presentation/web/    当前回环网关骨架；迁移后仅作为显式 Recovery Adapter
internal/textcodec/           纯 Go 编码注册表、流式转码与热切换
internal/application/preferences/ 语言与默认编码偏好、CAS 持久化
internal/platform/            Windows/macOS/Linux 平台适配器
frontend/                     Vue 3 + TypeScript 管理界面
scripts/                      本地构建和质量门禁
docs/                         需求、架构、详细设计、测试与 UI 规范
```

## 本地开发

要求：Go 1.25+、Node.js 24+、npm 11+。

```powershell
cd frontend
npm ci
npm run build
cd ..

$env:CGO_ENABLED = '0'
go run ./cmd/opsconn-desktop --data-dir ./.local-data
```

默认启动模式为 **desktop**：使用系统 WebView（Windows WebView2 / macOS WebKit / Linux WebKitGTK）渲染嵌入的前端，不打开本地 TCP 监听端口，不调用系统浏览器。

常用参数：

- `--data-dir <path>`：指定数据目录；
- `--portable`：将数据放在二进制旁的 `data` 目录（绿色免安装模式）；
- `--ui-mode desktop|recovery-web|browser`：选择 UI 传输层，默认 `desktop`；
- `--recovery-ui`：等价于 `--ui-mode recovery-web`，启动 loopback HTTP 网关用于诊断，不自动打开浏览器；
- `--browser`：等价于 `--ui-mode browser`，启动 loopback HTTP 网关并打开系统浏览器；
- `--log-level debug|info|warn|error`：设置结构化日志级别。

### UI 模式说明

| 模式 | 传输方式 | TCP 监听 | 自动打开浏览器 | 适用场景 |
|------|---------|---------|--------------|---------|
| `desktop` (默认) | 系统 WebView 窗口 | 否 | 否 | 生产默认，跨平台 |
| `recovery-web` | Loopback HTTP/WS | 是 (127.0.0.1:0) | 否 | 诊断、WebView 不可用时 |
| `browser` | Loopback HTTP/WS | 是 (127.0.0.1:0) | 是 | 开发、无头环境有显示 |

## 构建与验证

```powershell
# 当前平台的发布构建
./scripts/build.ps1 -Version 0.1.0

# 格式、前端类型、单测、vet、纯 Go 六目标交叉编译
./scripts/verify.ps1
```

产物默认写入 `build/`。CI 覆盖 Windows、macOS、Linux 的 amd64/arm64 交叉编译，并在 Linux 执行竞态检测。

## 下一阶段接入方式

连接器必须依赖统一的 `DialRoute`、`SecretRef`、Governor 配额、Supervisor 生命周期和 typed error，不得自行创建无界协程、旁路凭据保险箱或绕开 SSH 隧道路由。推荐顺序为 SSH/SFTP → MySQL/PostgreSQL/SQLite → Redis/ClickHouse → Kafka/Elasticsearch/MongoDB → MSSQL/Oracle/ETCD/串口及网络设备。