serviceport

本地 SQLite 文件支持：侧边栏“SQLite 文件”可测试文件连接、查看表/视图结构并执行只读 SQL 查询，详见 SQLite 使用说明。

开发时双击根目录 start-dev.cmd，系统自动分配空闲管理端口，并打开实际地址（默认免登录）。启动窗口会显示 http://127.0.0.1:<实际端口>，每次启动端口可能不同。该入口先切换到自身目录，不再设置数据库路径；程序优先使用显式 SERVICEPORT_DATA，否则依次查找当前目录 data/serviceport.sqlite、%APPDATA%\serviceport\serviceport.sqlite，复用第一个已有数据库，都不存在才在当前目录的 data 新建。数据库、master-key.dpapi、审计和 TLS 文件保持同目录关联，重启复用配置；启动脚本备份实际选中的完整数据目录。密钥绑定当前 Windows 用户，不会自动搬移或合并不同目录的数据。

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

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

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

能力

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

目标服务支持可选分组，可按分组筛选，并在网关选择目标时显示分组。独立「代理」菜单维护通用 SOCKS5、SSH 转发与 K8s port-forward 配置。目标服务通过「代理出口」下拉框选择，或选择「直接连接」。多个目标可以共用同一代理；代理被引用时禁止删除，修改前须停止全部关联网关。旧目标内的出口配置升级时自动迁移，配置和凭据保留；升级前停止服务并备份整个数据目录。

「资产管理」集中上传和更新 Kubeconfig、SSH 私钥、公钥列表、SSH 用户证书、TLS/CA 证书和其他文本配置文件，内容加密保存到数据库。目标、账号和代理按类型引用资产；文件失效后更新同一资产即可，更新前需停止关联网关，被引用的资产不能删除。操作说明见 文件资产管理、Kubernetes 配置 和 配置操作与易用性。

网关账号在配置抽屉的独立「账号」页签维护。来源 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；出口失败不回退直连。
• 个人工作台：可选个人登录，SQLite 加密配置、CSRF/会话、密码重新认证查看、来源白名单、连接限额、启停及 7 天审计。支持短期 API Token、作用域控制和 Prometheus 指标，不提供管理用户或角色分配。

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

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

配置中心支持 S3 多端同步，在设备间加密同步目标、代理、资产、凭据和网关配置，支持手动及定时同步、删除传播与冲突选择，使用 ETag 条件写入防止并发覆盖。设置方式见 S3 多端同步。

运行中的网关支持通过「切换目标」或「拖拽连线」调整目标服务及共用账号。监听保持运行，新连接使用新目标，已有连接保留原目标。详见 运行中切换目标。

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

目标版本与实测版本请区分，见 验证说明。

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

构建

项目包含 .drone.yml，定义 Go 全量测试、go vet、前端生产构建和无 CGO Linux amd64 编译。当前 Linux 构建与发布段仍引用旧 agentdb 名称和 cmd/agentdb 入口，修正前不能完成当前项目发布。流水线不连接真实数据库，不读取 data/；真实服务矩阵仍使用 scripts/test-matrix.ps1 或 scripts/test-matrix.sh。 流水线还定义了 Linux 打包与 tag 触发的 IPFS 上传步骤；修正上述旧入口并配置 ipfs_api / ipfs_token Secret 后可用于发布，详见 Drone/IPFS 发布说明。

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

目标出口新增内置 K8s port-forward，不依赖 kubectl，支持 Pod、Service、Deployment 和 StatefulSet。配置与权限见 Kubernetes 说明。

需要 Node.js 22.12+ 和 Go。当前 Vitess 解析器固定使用 Go 1.25.0；机器安装更新版 Go 时，设置 GOTOOLCHAIN=go1.25.0 自动使用兼容工具链。不要直接用 Go 1.27 编译该版本 Vitess。

Windows PowerShell：

.\scripts\build.ps1

Linux / macOS：

sh scripts/build.sh

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

启动

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

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

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

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

未设置 SERVICEPORT_MASTER_KEY 时，Windows 自动进入本地模式：显式 SERVICEPORT_DATA 优先，否则按“当前目录 data/serviceport.sqlite → %APPDATA%\serviceport\serviceport.sqlite”查找已有数据库；都没有则在当前目录 data 新建。SERVICEPORT_DATA 支持相对或绝对文件路径，显式指定后不再遍历。密钥使用当前 Windows 用户的 DPAPI 加密保存，自动创建有效期一年的 localhost TLS 证书。选中的库缺密钥、被占用或损坏时直接报错，不跳过它另建空库。直接从其他目录运行 EXE 会改变当前目录候选；start-dev.cmd 以入口目录为基准，并保留外部显式路径。可用 .\serviceport.exe data-path 查看最终路径，此命令不创建数据库或密钥。备份完整目录；跨机器迁移仍须遵守 DPAPI 用户/机器绑定限制。详见 Windows 使用说明。

以下为服务器部署 / 手动管理密钥的 PowerShell 示例（设置主密钥后保留原有启动行为）：

$env:SERVICEPORT_AUTH_ENABLED = 'true'
$env:SERVICEPORT_MASTER_KEY = .\bin\serviceport.exe generate-key
$env:SERVICEPORT_ADMIN_USER = 'admin'
$adminSecret = Read-Host '初始登录密码（12–72 字节）' -AsSecureString
$env:SERVICEPORT_ADMIN_PASSWORD = [Net.NetworkCredential]::new('', $adminSecret).Password
.\bin\serviceport.exe

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

首次生成的主密钥必须保存并在后续启动时复用，不能每次启动重新生成。数据库备份需要同时备份主密钥；换错密钥时已保存配置无法解密。

环境变量	默认值 / 用途
SERVICEPORT_AUTH_ENABLED	默认 false，开发阶段免登录且仅限本机；true 启用个人登录
SERVICEPORT_MASTER_KEY	服务器模式必填，32 字节随机密钥的 Base64；Windows 未设置时启用本地模式
SERVICEPORT_ADMIN_USER	手动密钥模式且启用认证时，首次启动必填
SERVICEPORT_ADMIN_PASSWORD	手动密钥模式且启用认证时，首次启动必填，12–72 字节
SERVICEPORT_DATA	留空自动选择；Windows 本地模式优先当前目录已有库，再查 AppData，新库使用 data/serviceport.sqlite
SERVICEPORT_HTTP_ADDR	127.0.0.1:0（系统分配空闲端口；可显式指定固定端口）
SERVICEPORT_NO_BROWSER	Windows 本地模式设为 1 可禁用自动打开浏览器
SERVICEPORT_SECURE_COOKIE	默认 false；管理界面经 HTTPS 访问时设为 true
SERVICEPORT_TLS_CERT / SERVICEPORT_TLS_KEY	数据库网关客户端 TLS 证书和私钥路径

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

API 自动化

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

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 天的证书：

$env:GOTOOLCHAIN = 'go1.25.0'
go run ./cmd/devcert
$env:SERVICEPORT_TLS_CERT = 'data/tls/cert.pem'
$env:SERVICEPORT_TLS_KEY = 'data/tls/key.pem'
.\bin\serviceport.exe

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

SSH 主机身份

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

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

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

密码查看与重置

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

.\bin\serviceport.exe reset-password

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

开发与测试

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

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

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

Windows 便携包

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

.\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 打包；窗口保留结果，命令行自动化可设置 SERVICEPORT_PACKAGE_NO_PAUSE=1 取消暂停。版本默认读取 VERSION。

默认使用快速 ZIP 压缩，并输出前端、Go 编译、验证、压缩各阶段耗时。需要更小的压缩包时运行 .\package.cmd -Compression Optimal，耗时会增加。前端按源码、配置、依赖锁文件、Node 版本及产物内容校验缓存，变化或缺失时自动重建；依赖变化自动执行 npm ci。可用 .\package.cmd -RebuildWeb 强制重建前端。缓存位于 artifacts/build-cache。Go 每次构建当前代码、注入最新版本信息，并自动复用编译缓存；发布包验证始终执行。

start-dev.cmd 用于直接启动。源码目录默认快速构建：复用前端依赖和构建缓存，跳过启动前的 Go 全量测试；Go 每次编译当前源码、注入最新构建信息，并复用 Go 编译缓存。先生成 artifacts/dev-build/serviceport.exe，成功后才停止当前目录中的旧服务并等待退出，将整个 data 备份到 artifacts/backups/<时间>/，再替换并运行 bin/serviceport.exe。构建失败时保留原服务运行；数据备份始终在停服后进行。日志显示前端、测试（启用时）、Go 构建和总耗时。

.\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 正在嵌入的前端资源。

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

打包脚本按需构建前端并编译 Windows x64 程序，自动验证文件校验值、隔离启动、网页资源与个人登录，通过后在 artifacts/releases/<时间>/ 生成 ZIP 及 SHA-256 校验文件。包内包含主程序、开发证书工具、独立启动说明和配置示例，不包含本地数据库或凭据。解压后也可用 node scripts/verify-package.mjs <解压后的包目录> 重复验证。打包不会替换正在运行的服务。

文档

• UI 实现状态与待验收事项
• 资源搜索、资源树、列设置与工作区标签
• 变更原因与设计记录
• 未保存配置的连接测试
• 配置操作与易用性
• 连接页签与 URL 参数
• 开发计划
• 只读规则与兼容边界
• 测试、版本矩阵与验证状态

目标压缩与命令审计

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

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

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

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

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