LinkPort/README.md

# linkport

<img src="web/public/linkport.svg" alt="linkport 项目图标" width="72" height="72" />

正常启动时打印项目标识与版本信息；图标设计和命令输出兼容性见 [项目标识说明](docs/branding.md)。

开发时双击根目录 `start-dev.cmd`，系统自动分配空闲管理端口，并打开实际地址（默认免登录）。启动窗口会显示 `http://127.0.0.1:<实际端口>`，每次启动端口可能不同。该入口先切换到自身目录，不覆盖 `LINKPORT_DATA`；Windows 本地模式优先指定路径，否则依次查找当前目录 `data/linkport.sqlite`、旧 `%APPDATA%\linkport\linkport.sqlite`，均不存在才在当前目录新建。Windows、Linux、macOS 默认均使用单 SQLite 保存配置、主密钥、审计和自动 TLS，不依赖 `master-key.dpapi` 或主密钥环境变量。升级旧库前须停服并备份完整旧目录，详见 [单文件存储与迁移](docs/single-file-storage.md)。

使用 Go 和 Vue 3 构建的 MySQL、MongoDB、PostgreSQL、SQL Server、Redis、RabbitMQ、SSH、SFTP、HTTP/HTTPS 连接代理管理后台。目标服务独立保存地址、凭据及直连 / SOCKS5 / SSH / sing-box 出口；网关引用目标，独立管理监听端口、访问凭据及可选只读策略。一个目标可被多个同协议网关复用。

目标配置的「代理出口」可选择 SSH 转发，填写跳板机地址、端口、账号密码和已核对的 SHA256 主机指纹。跳板机需允许 TCP 转发；目标地址和域名由跳板机访问，连接失败不回退直连。当前跳板机认证支持密码。网关来源 IP/CIDR 为可选项，留空允许所有来源，填写后仅放行匹配项。

**MySQL、MongoDB 默认读写，只读模式按代理可选启用。** 只读基于网关严格白名单，不自动修改目标数据库权限。

## 能力

- **TCP 端口映射**：默认监听 `0.0.0.0`，支持直连、SSH/SOCKS5 出口和 K8s 资源转发。纯字节透传，无网关账号认证、TLS 终止或只读控制；请配置来源白名单和防火墙。详见 [TCP 端口映射](docs/tcp-port-mapping.md)。

想了解每个模块的用途、代码位置和依赖关系，见 [模块说明与代码导航](docs/modules.md)。文档覆盖核心对象、后端模块、全部协议、前端组件、构建部署与常见修改入口。

目标服务支持可选分组，可按分组筛选，并在网关选择目标时显示分组。「代理管理 → 新建代理」在顶部直接选择 Kubeconfig、SSH、SOCKS5 或 sing-box，独立保存网络连接配置。目标在「连接方式」中按类型选择已保存代理，或明确选择直连；普通网关继承目标的代理，TCP 纯端口转发网关也能直接引用代理。共享代理被引用时禁止删除，修改前须停止关联网关。旧配置和凭据保留，本次无数据库迁移，详见 [网络代理管理](docs/network-proxies.md)。

文件作为连接凭据在需要的表单内选择或上传，代理管理不提供通用文件列表。Kubeconfig、SSH 私钥、公钥列表、用户证书与 TLS/CA 证书仍加密保存并可复用；旧文件通过资源搜索或引用跳转编辑，更新前需停止关联网关，被引用的文件不能删除。操作说明见 [文件凭据兼容说明](docs/file-assets.md)、[Kubernetes 配置](docs/kubernetes.md) 和 [配置操作与易用性](docs/usability.md)。

网关账号在配置抽屉的独立「账号」页签维护。来源 IP/CIDR 使用单行输入，多项以逗号分隔；账号白名单还须同时满足「网关与访问」页中的网关白名单。拖拽连接页支持确认断开已停止网关的关联，保留网关账号，并可重新拖拽关联目标。

- MySQL：统一账号、TLS、查询、事务、二进制预编译和可选只读；目标版本为 5.7.44、8.0、8.4。
- MongoDB：双端 SCRAM-SHA-256、TLS、CRUD、聚合、游标及可选只读；目标版本为 6.0、7.0、8.0，客户端必须设置 `directConnection=true`。
- SSH：密码/公钥登录网关，上游密码/私钥认证，固定主机指纹，交互终端、远程命令和 SFTP。
- Redis：RESP 数组命令、AUTH/HELLO 凭据映射、流水线、订阅推送与命令审计；支持 standalone 目标，不自动处理 Cluster 重定向。
- RabbitMQ：AMQP 0-9-1、PLAIN 凭据映射、队列/交换机/发布消费帧转发；审计方法及通道元数据，不保存消息正文。
- PostgreSQL（pgsql）：普通和扩展查询协议、上游 MD5/SCRAM 认证、网关密码认证、参数化查询及 SQL 审计。当前不代理独立 CancelRequest，也不提供只读策略。
- SQL Server：TDS 7.x SQL 密码登录、TLS 协商、网关账号到目标账号映射及 SQL Batch/RPC 审计；当前不支持集成 Windows/Kerberos 登录。
- HTTP/HTTPS：网关 Basic Auth、目标 Basic Auth 替换、TLS、请求审计和来源限制；仅转发普通 HTTP 请求，不支持 CONNECT 或 WebSocket 升级。
- SFTP：复用 SSH 主机指纹和账号认证，仅开放 SFTP 子系统；文件操作写入审计，不记录文件内容。
- SOCKS5：每条代理独立配置，支持无认证和用户名密码认证、远端 DNS；出口失败不回退直连。
- sing-box：连接资产保存一个受限的远程 outbound JSON；linkport 管理 loopback SOCKS5 入站与外部子进程。binary 不随发布包提供，通过 `LINKPORT_SING_BOX` 或 `PATH` 定位；配置检查不等于真实目标连通。详见 [sing-box 连接资产](docs/sing-box.md)。
- 个人工作台：可选个人登录，SQLite 加密配置、CSRF/会话、密码重新认证查看、来源白名单、连接限额、启停及 7 天审计。支持短期 API Token、作用域控制和 Prometheus 指标，不提供管理用户或角色分配。

网关支持多个独立账号，可暂不关联目标；账号支持禁用、来源限制，MySQL/MongoDB 支持账号只读策略。新增批量创建和启停、健康检查与指标、加密配置备份及历史恢复。使用方式、旧配置迁移与验证边界见 [网关账号与运维](docs/gateway-operations.md)，双实例部署示例见 [高可用部署](docs/high-availability.md)。

「配置管理」通过「导出配置」入口导出全部配置，使用口令加密，包含资产管理的全部文件内容、文件名、引用关系及恢复所需凭据。导入时需要相同口令。配置模板不包含资产文件内容及凭据，适合分享配置结构。导入预览按与实际导入相同的合并规则校验现有引用，展示新增、覆盖、未变更资源及脱敏字段差异，不写入数据库。确认前须手动停止所有网关；预览后配置发生变化会拒绝提交并要求重新预览。详见 [配置备份与资产文件](docs/configuration-backup.md)。

配置中心支持 WebDAV 多端同步，在设备间加密同步目标、代理、资产、凭据和网关配置，支持手动及定时同步、独立加密备份、删除传播与冲突选择，使用 ETag 条件写入防止并发覆盖。设置方式见 [WebDAV 多端同步](docs/webdav-sync.md)。

运行中的网关支持通过「切换目标」或「拖拽连线」调整目标服务及账号映射。保存成功后监听保持运行，现有客户端连接会断开，客户端重连后使用新目标；保存失败不影响原连接。详见 [运行中切换目标](docs/live-target-switch.md)。

「密码解密」支持选择算法、分组模式、填充方式、Key、IV 和编码；选择 Navicat 12 自动填入 AES / CBC / PKCS7 参数，也支持 Navicat 11 格式。详见 [密码解密工具](docs/navicat-decryption.md)。全项目页面支持手机、平板及宽屏布局，见 [响应式界面](docs/responsive-ui.md)。

目标版本与实测版本请区分，见 [验证说明](docs/testing.md)。

「拖拽连接」可从网关账号连接到同协议目标账号并保存关联，也支持点击选择；运行中切换会断开该网关的现有连接，重连后使用新映射。命令审计与连接事件按 UTC 日期保存至 `data/audit/YYYY-MM-DD.sqlite`（每库分别包含 commands/events），保留 7 天。旧记录启动时自动迁移；配置库继续固定使用 `data/linkport.sqlite`。两类日志均支持跨天筛选、分页和 CSV 全量导出；命令内容仍加密保存，导出只包含当前保留且已记录的内容。备份请停止服务并复制整个 `data` 目录。

## 构建

项目包含 `.drone.yml`，执行前端构建、Go 1.27.1 无 CGO 六平台编译、发布脚本测试及 Linux amd64 隔离启动验证。linux/amd64、linux/arm64、windows/amd64、windows/arm64、darwin/amd64、darwin/arm64 依次构建，平台并发和 Go 编译并发默认均为 1。六个独立压缩包保留在 `bin/releases/ci/`，附发布清单和 SHA256；打包成功后直接上传 IPFS，再发布下载索引目录并输出完整下载地址，不按构建事件跳过。API 与认证令牌直接配置在 YAML 中，无需 Drone Secret；令牌对仓库读者可见。不再构建或推送 Docker 镜像，也不使用 Gitea 包仓库，详见 [Drone/IPFS 发布说明](docs/ipfs.md)。流水线不读取真实 `data/`；真实服务矩阵仍使用 `scripts/test-matrix.ps1` 或 `scripts/test-matrix.sh`。

项目版本统一维护在根目录 `VERSION`。`linkport.exe version` 或 `linkport.exe --version --json` 可查看版本、Git 提交、构建时间与平台，管理界面顶部也可查看版本信息。构建/打包脚本自动注入元数据；直接 `go build` 仍使用 VERSION 的版本值，但提交和时间可能显示 `unknown`。

目标出口新增内置 `K8s port-forward`，不依赖 kubectl，支持 Pod、Service、Deployment 和 StatefulSet。配置与权限见 [Kubernetes 说明](docs/kubernetes.md)。

需要 Node.js 22.12+ 和 **Go 1.27.1**。设置 `GOTOOLCHAIN=go1.27.1` 使用与当前依赖和构建脚本一致的工具链。

Windows PowerShell：

```powershell
.\scripts\build.ps1
```

源码目录的 `start-dev.cmd` 需要 Go、Node.js 和 npm；它不是免编译的发行版启动器。脚本以项目自身位置为基准，优先使用 `tools/go/bin/go.exe` 和 `tools/node/node.exe`（完整工具链含 npm），否则从 PATH 查找，不写死机器安装路径。可将项目和工具目录一起复制到其他电脑；详见 [相对路径与便携构建](docs/build-output.md)。不需要开发环境时直接运行预编译发行版 `linkport.exe`。

Linux / macOS：

```sh
sh scripts/build.sh
```

脚本安装前端依赖、构建 Vue、执行 Go 测试并生成 `bin/linkport`（Windows 为 `.exe`）。前端嵌入可执行文件，部署不需要 Node.js。

构建缓存、发布包和升级备份也统一放在 `bin/` 子目录，详见 [本地输出目录](docs/build-output.md)。`bin/backups/` 含用户数据，清理构建产物时应保留或先转存。

## 启动

Windows 本地使用：解压发行包后双击 `linkport.exe`，浏览器自动打开，**开发阶段默认免登录**，直接进入控制台。无需安装 Go/Node.js，无需设置环境变量。保持程序窗口运行，按 Ctrl+C 停止服务。

先在「目标服务」中添加 MySQL/MongoDB/SSH 目标，再在「网关服务」中选择目标并配置监听、网关账号和访问策略。目标被引用时不能删除；编辑目标前需要停止所有引用它的网关。旧版配置会在事务中自动拆分，保留网关 ID、凭据、SSH 指纹和启用状态，升级前先停止服务并备份数据目录。

右上角可切换浅色、深色、海蓝及跟随系统主题，选择保存在当前浏览器中。

免登录模式仅允许回环地址访问，仍校验请求来源与 CSRF。设置 `LINKPORT_AUTH_ENABLED=true` 可启用个人登录；本地模式会在尚无账号时打开首次设置页面，已有账号直接登录。旧版附加用户及其 Token 不再可用，初始账号继续使用。远程服务器部署必须开启认证。

Windows、Linux、macOS 的回环管理地址自动使用本地模式；所有平台的随机主密钥和自动 TLS 均保存在 SQLite 内。`LINKPORT_DATA` 支持相对或绝对文件路径，显式指定后不再搜索。选中的库被占用、损坏，或旧库缺少迁移密钥时直接报错，不另建空库。可用 `.\linkport.exe data-path` 查看最终路径，该命令不创建数据库。升级前备份完整旧目录；完成迁移且正常停服后，仅复制 SQLite 即可跨机器使用。数据库文件包含完整解密材料，必须限制访问。详见 [Windows 使用说明](packaging/windows/README.md) 和 [单文件存储](docs/single-file-storage.md)。

以下为启用登录的 PowerShell 示例（无需配置主密钥）：

```powershell
$env:LINKPORT_AUTH_ENABLED = 'true'
$env:LINKPORT_ADMIN_USER = 'admin'
$adminSecret = Read-Host '初始登录密码（12–72 字节）' -AsSecureString
$env:LINKPORT_ADMIN_PASSWORD = [Net.NetworkCredential]::new('', $adminSecret).Password
.\bin\linkport.exe
```

打开启动窗口打印的管理页面地址。默认由系统分配空闲端口；需要固定地址时，可在启动前设置 `LINKPORT_HTTP_ADDR=127.0.0.1:8080`。个人账号只在首次运行创建，之后不会用环境变量覆盖密码。`LINKPORT_ADMIN_USER` 和 `LINKPORT_ADMIN_PASSWORD` 保留原名称以兼容现有启动配置。

主密钥由程序在首次初始化时写入 SQLite，后续自动复用，不再读取 `LINKPORT_MASTER_KEY`。旧外部密钥库使用 `migrate-key` 命令做一次性迁移；运行中的 WAL/SHM 文件不能忽略，单文件复制须先正常停服。

| 环境变量 | 默认值 / 用途 |
| --- | --- |
| `LINKPORT_AUTH_ENABLED` | 默认 `false`，开发阶段免登录且仅限本机；`true` 启用个人登录 |
| `LINKPORT_ADMIN_USER` | 非桌面模式启用认证时，首次启动必填 |
| `LINKPORT_ADMIN_PASSWORD` | 非桌面模式启用认证时，首次启动必填，12–72 字节 |
| `LINKPORT_DATA` | 留空自动选择；Windows 本地模式优先当前目录已有库，再查 AppData，新库使用 `data/linkport.sqlite` |
| `LINKPORT_HTTP_ADDR` | `127.0.0.1:0`（系统分配空闲端口；可显式指定固定端口） |
| `LINKPORT_NO_BROWSER` | 本地模式设为 `1` 可禁用自动打开浏览器 |
| `LINKPORT_SECURE_COOKIE` | 默认 `false`；管理界面经 HTTPS 访问时设为 `true` |
| `LINKPORT_TLS_CERT` / `LINKPORT_TLS_KEY` | 数据库网关客户端 TLS 证书和私钥路径 |
| `LINKPORT_SING_BOX` | 可选的 sing-box binary 绝对路径或可由 `PATH` 解析的命令；留空时查找 `sing-box`。仅使用 sing-box 连接资产时需要，发布包不捆绑 |

`.env.example` 仅为示例，程序不自动加载 `.env`。远程管理使用 HTTPS 反向代理。

### API 自动化

你可在「监控运维 → API Token」创建短期 Token、选择作用域与到期时间、查看状态及撤销；创建需要启用个人登录。也可使用管理 API，创建请求示例：

```http
POST /api/v1/tokens
Content-Type: application/json
X-CSRF-Token: <session-csrf>

{"name":"monitoring-ci","scopes":["metrics"],"expiresAt":"2026-12-31T00:00:00Z"}
```

响应中的 `secret` 只返回一次，后续请求使用 `Authorization: Bearer <secret>`。作用域为 `read`、`write`、`audit`、`metrics`；Token 不能创建 Token、读取秘密或修改 Webhook 设置，写入响应也会清除敏感字段。`DELETE /api/v1/tokens/{id}` 可撤销 Token；个人登录密码重置后 Token 失效，单纯退出网页登录不会使其失效。指标通过 `GET /api/v1/metrics` 以 Prometheus 文本格式返回。

「监控运维 → 配置模板」支持将当前配置存为模板、导入模板文件、查看和导出 JSON、补齐凭据后预览应用及删除。模板只保存脱敏结构，可在个人工作台管理。健康检查间隔持久保存，重启后恢复，每轮检查所有目标账号；设为 0 可关闭。

周期健康检查最多并发 4 个账号，取消任务时保留上次结果。监控页面每 5 秒刷新，后台标签页暂停新请求，刷新保留未保存的间隔设置。配置历史忽略切换资源后迟到的响应，恢复确认明确显示资源和版本。

### 数据库 TLS

MySQL/MongoDB 网关允许普通连接；配置证书后同一端口也支持客户端选择 TLS。未配置证书仍可启动数据库网关并接受普通连接。客户端 TLS 与目标服务的上游 TLS 独立。

本机开发可生成只覆盖 `localhost`、`127.0.0.1` 和 `::1`、有效期 14 天的证书：

```powershell
$env:GOTOOLCHAIN = 'go1.27.1'
go run ./cmd/devcert
$env:LINKPORT_TLS_CERT = 'data/tls/cert.pem'
$env:LINKPORT_TLS_KEY = 'data/tls/key.pem'
.\bin\linkport.exe
```

客户端将 `cert.pem` 作为 CA 验证；局域网正式使用时换成覆盖实际网关域名的受信任证书。目标数据库 TLS 独立配置，默认验证系统 CA 或配置中提供的 PEM CA，不提供跳过验证模式。

### SSH 主机身份

同一份 linkport 数据库中的全部 SSH/SFTP 网关共用一份 Ed25519 主机密钥，加密独立保存。停启服务、修改配置、新建网关，以及删除全部网关后重新创建，均保留同一指纹；目标服务器的主机指纹校验仍各自独立。

升级前停止服务并备份完整 `data` 目录（含数据库与主密钥）。首次升级按网关 ID 排序，沿用第一个有效的 Ed25519 主机密钥并统一现有网关；没有有效密钥时生成一份。原指纹不同的端口需核对界面中的“网关指纹”，再更新客户端 `known_hosts`。向已有实例导入配置或恢复历史不会替换共用密钥；向空实例恢复含 SSH/SFTP 网关的加密备份时沿用备份中的密钥。完整数据目录备份也会保留没有任何网关时的共用密钥。

保存 SSH 配置后，使用代理菜单“探测 / 确认主机指纹”。探测不发送目标账号凭据；通过独立可信渠道核对指纹后输入完整指纹确认，再启动代理。主机密钥变化会拒绝连接；修改目标地址或端口需要重新确认。

### 密码查看与重置

目标、网关、SOCKS5 密码和 SSH 私钥口令可在重新验证登录密码后查看，30 秒自动隐藏并记录审计。SSH 私钥不可下载。个人登录密码仅保存 bcrypt 哈希，只能重置：

```powershell
.\bin\linkport.exe reset-password
```

重置命令使用同一个数据路径和主密钥，交互输入密码并使旧会话失效。

## 开发与测试

```powershell
$env:GOTOOLCHAIN = 'go1.27.1'
go test ./...
go vet ./...
npm.cmd --prefix web run build
go build -o bin/linkport.exe ./cmd/linkport
node scripts/verify-random-port.mjs bin/linkport.exe
npm.cmd --prefix web test
```

前端独立开发：先设置 `$env:LINKPORT_HTTP_ADDR='127.0.0.1:8080'` 再启动后端，然后运行 `npm --prefix web run dev`；Vite 将 `/api` 转发到该固定端口。直接使用 `start-dev.cmd` 的内嵌页面则默认使用随机空闲端口。浏览器测试启动隔离的临时数据服务，默认使用已安装的 Edge；其他平台可设置 `LINKPORT_BROWSER_CHANNEL=chromium` 并先运行 `npx playwright install chromium`。

Docker 构建：`docker build -t linkport .`。容器默认以 UID 10001 运行，数据卷须可写；代理监听端口需要自行映射。数据库版本矩阵见 [验证说明](docs/testing.md)。

## Windows 便携包

所有协议的目标服务统一使用账号列表（例如普通账号、root），不再单独填写一组用户名和密码。在目标编辑的“账号”页签中维护，在网关编辑的“目标账号”中选择。开发阶段不兼容旧账号设计：旧目标需重新配置账号，旧网关需重新选择账号才能启动，不自动迁移或回退。用户只使用网关凭据；root 账号为直接 SSH 登录，不是 sudo 提权。详见 [目标多账号](docs/target-accounts.md)。

```powershell
.\package.cmd
# Optional version override:
.\package.cmd -Version 0.3.0
# PowerShell entry:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/package.ps1
```

安装 Go、Node.js/npm 后，可双击根目录 `package.cmd` 打包；窗口保留结果，命令行自动化可设置 `LINKPORT_PACKAGE_NO_PAUSE=1` 取消暂停。版本默认读取 `VERSION`。

最终交付目录 `bin/releases/<时间与唯一标识>/` 只包含 `linkport.exe`，直接双击即可运行。网页已嵌入程序，不再输出 ZIP、额外工具、脚本、说明文件或校验文件；旧 `-Compression` 参数已移除。版本、提交和构建时间可通过 `linkport.exe --version --json` 查看，EXE 的 SHA-256 显示在打包日志中。前端按源码、配置、依赖锁文件、Node 版本及产物内容校验缓存，变化或缺失时自动重建；依赖变化自动执行 `npm ci`。可用 `.\package.cmd -RebuildWeb` 强制重建前端。缓存位于 `bin/build-cache`。Go 每次构建当前代码并注入版本信息；构建和验证均在临时构建目录完成，只有验证成功才生成最终交付目录。

`start-dev.cmd` 用于直接启动。源码目录默认快速构建：复用前端依赖和构建缓存，跳过启动前的 Go 全量测试；Go 每次检查当前源码和内嵌资源，未变化时直接复用候选 EXE。开发模式保留版本与提交，构建时间显示 `unknown`，避免每次启动因时间戳变化强制重新链接；发布打包仍记录实际构建时间。先生成 `bin/dev-build/linkport.exe`，成功后才停止当前目录中的旧服务并等待退出，将整个 `data` 备份到 `bin/backups/<时间>/`，再替换并运行 `bin/linkport.exe`。构建失败时保留原服务运行；数据备份始终在停服后进行。日志显示前端、测试（启用时）、Go 构建和总耗时。

```powershell
.\start-dev.cmd                       # 缓存构建并启动
.\start-dev.cmd -FullCheck            # 构建时附加 Go 全量测试
.\start-dev.cmd -RebuildWeb           # 强制重建前端
.\start-dev.cmd -BuildOnly            # 只构建临时产物，不停服、不备份、不启动
.\start-dev.cmd -BuildOnly -FullCheck # 只构建并执行 Go 全量测试
```

首次运行或依赖锁文件变化时执行 `npm ci`；前端源码、配置、构建环境或产物变化时重建前端。直接运行 `scripts/build.ps1` 仍默认执行 Go 全量测试，支持 `-SkipTests`、`-RebuildWeb` 和 `-OutputPath`。`scripts/start-dev.test.ps1` 使用临时目录验证启动参数、仅构建模式与失败保护。

Windows 开发构建和发布打包共用构建锁；已有构建运行时，第二次构建会明确报错，完成后可重试。构建期间不要另行运行 Vite，以免替换 Go 正在嵌入的前端资源。

单 EXE 交付不附带启动脚本，也不捆绑可选的 sing-box binary。仓库中的启动脚本仍兼容旧发布目录（没有构建脚本时直接运行根目录的 `linkport.exe`）；构建参数仅适用于源码目录。`start-dev.cmd` 先切换到入口所在目录，通过相对路径调用 PowerShell，退出后恢复调用者目录；直接执行 `scripts/start-dev.ps1` 也会先切到项目/解压根目录。脚本不设置或覆盖 `LINKPORT_DATA`，使用程序的 `data-path` 命令确定备份目录；先停本项目旧服务，再锁定并备份实际数据目录，然后启动。其他实例占用数据或数据目录包含备份目标时拒绝备份启动。默认免登录，自动分配空闲端口并打开浏览器；实际地址见启动窗口。启动脚本尊重显式设置的 `LINKPORT_HTTP_ADDR`，需要稳定 API 地址或反向代理时请指定固定端口。快速构建不会省略完整数据备份，大审计目录的备份仍可能花费时间。

打包脚本编译 Windows x64 单文件程序，自动验证目录只有一个 EXE、内嵌版本信息、隔离启动、网页资源与个人登录。可用 `node scripts/verify-package.mjs <交付目录或linkport.exe路径>` 重复验证，测试数据写入独立临时目录。文档和配置示例保留在源码仓库。运行后使用单 SQLite 保存配置、密钥、审计及自动 TLS；“单 EXE”指交付文件，不表示运行数据被写进 EXE。打包不包含实际数据或凭据，不替换正在运行的服务；更新已有数据前仍需停服并备份完整数据目录。

## 文档

- [UI 实现状态与待验收事项](docs/todo.md)
- [资源搜索、资源树、列设置与工作区标签](docs/workspace-ui.md)
- [变更原因与设计记录](docs/change-rationale.md)
- [未保存配置的连接测试](docs/target-connection-test.md)
- [配置操作与易用性](docs/usability.md)
- [连接页签与 URL 参数](docs/connection-editor.md)
- [sing-box 连接资产、安装与安全边界](docs/sing-box.md)
- [开发计划](docs/development-plan.md)
- [只读规则与兼容边界](docs/readonly.md)
- [测试、版本矩阵与验证状态](docs/testing.md)

## 目标压缩与命令审计

MySQL/MongoDB 目标可选择 zlib 压缩（默认关闭），通过协议协商启用，目标不支持时保持未压缩连接；连接测试显示实际协商结果。压缩仅作用于 linkport 到目标服务一侧，直连和 SOCKS5 均适用。当前 SSH 库仅支持未压缩传输。

「命令审计」记录 MySQL SQL/预编译模板、MongoDB 请求、SSH exec、交互输入行和 SFTP 操作，可按网关/协议筛选并分页查看。内容加密保存，保留 7 天。SSH 输入保留完整文本及原始按键，结合终端回显补齐 Tab 补全和历史召回；交互输入超过 1 MiB 时中止会话，不静默截断。其他协议沿用每条 16 KiB 的采集上限并标记截断。放行/拦截是网关决策，不表示目标执行成功。原始输入审计写入失败时不继续转发该命令。

SSH exec 关联保存标准输出、错误输出及服务器报告的退出码/信号；交互终端保存本次输入提交后到下次已记录输入或会话结束间的输出，不推断单条 shell 命令的退出码。输出分块加密保存，随命令保留 7 天，详情可分页查看和下载完整原始字节；页面预览上限不截断数据库输出。旧记录无法补录结果。

MySQL 普通查询和预编译执行关联保存返回列、数据行、影响行数及数据库错误，支持多个结果集。结果加密保存，详情支持表格分页和完整 NDJSON 下载；大整数、NULL、空字符串与二进制值分别保留，结果不按 SQL 文本上限截断。说明见 [MySQL 查询结果审计](docs/mysql-result-audit.md)。

不记录认证握手、SFTP 文件内容或其他协议的执行输出。MySQL 二进制预编译执行记录 SQL 模板、statement ID 与参数包字节数，不展开输入参数值；MongoDB 文档序列批量正文不展开，只记录命令主体及总字节数。SSH 无法确认的回显明确标为待确认，保留原始按键；脚本内部命令、关闭回显及复杂全屏程序仍不能作为远端执行追踪。命令列表和详情支持窄屏自适应，说明见 [SSH 终端审计](docs/ssh-command-audit.md)。