serviceport
开发时双击根目录 start-dev.cmd，打开 http://127.0.0.1:8080（默认免登录）。该入口固定使用项目根目录下的 data/serviceport.sqlite，与启动时的工作目录无关，重启和重新构建后继续保留目标服务和网关配置。数据库、master-key.dpapi 和 tls 均保存在 data 中，备份时关闭服务并复制整个目录；密钥绑定当前 Windows 用户。直接运行发布包仍使用 %APPDATA%/serviceport。
使用 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 支持账号只读策略。新增批量创建和启停、健康检查与指标、加密配置备份及历史恢复。使用方式、旧配置迁移与验证边界见 网关账号与运维，双实例部署示例见 高可用部署。
配置中心支持脱敏导出、加密备份、导入预览、配置模板和历史版本差异对比。导入预览按与实际导入相同的合并规则校验现有引用，展示新增、覆盖、未变更资源及脱敏字段差异，不写入数据库。确认前须手动停止所有网关；预览后配置发生变化会拒绝提交并要求重新预览。脱敏配置不会导出密码、私钥、口令或 Kubernetes 配置；加密备份包含用于恢复的凭据，须保管好备份口令。
目标版本与实测版本请区分，见 验证说明。
「拖拽连接」可将已停止的网关拖到同协议目标并保存关联，也支持点击选择。命令审计与连接事件按 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。配置与权限见 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 本地模式会在尚无管理员时打开首次设置页面，已有管理员直接登录。远程服务器部署必须开启认证。
未设置 SERVICEPORT_MASTER_KEY 时，Windows 自动进入本地模式：数据固定保存到 %APPDATA%\serviceport，密钥使用当前 Windows 用户的 DPAPI 加密保存，自动创建有效期一年的 localhost TLS 证书。备份整个目录；该密钥绑定 Windows 用户，不能直接复制到其他电脑使用。高级部署及跨机器迁移应使用自行保管的环境变量主密钥。详见 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
打开 http://127.0.0.1:8080。初始管理员只在首次运行创建，之后不会用环境变量覆盖密码。
首次生成的主密钥必须保存并在后续启动时复用，不能每次启动重新生成。数据库备份需要同时备份主密钥；换错密钥时已保存配置无法解密。
| 环境变量 | 默认值 / 用途 |
|---|---|
SERVICEPORT_AUTH_ENABLED |
默认 false，开发阶段免登录且仅限本机；true 启用管理员登录 |
SERVICEPORT_MASTER_KEY |
服务器模式必填，32 字节随机密钥的 Base64；Windows 未设置时启用本地模式 |
SERVICEPORT_ADMIN_USER |
手动密钥模式且启用认证时，首次启动必填 |
SERVICEPORT_ADMIN_PASSWORD |
手动密钥模式且启用认证时，首次启动必填，12–72 字节 |
SERVICEPORT_DATA |
data/serviceport.sqlite |
SERVICEPORT_HTTP_ADDR |
127.0.0.1:8080 |
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 主机身份
保存 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
npm.cmd --prefix web test
前端开发：npm --prefix web run dev，Vite 将 /api 转发到本机 8080。浏览器测试启动隔离的临时数据服务，默认使用已安装的 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，构建参数仅适用于源码目录。此入口固定使用入口所在目录的 data/serviceport.sqlite，默认免登录，访问 http://127.0.0.1:8080。快速构建不会省略停服后的完整数据备份，大审计目录的备份仍可能花费时间。
打包脚本按需构建前端并编译 Windows x64 程序，自动验证文件校验值、隔离启动、网页资源与管理员登录，通过后在 artifacts/releases/<时间>/ 生成 ZIP 及 SHA-256 校验文件。包内包含主程序、开发证书工具、独立启动说明和配置示例，不包含本地数据库或凭据。解压后也可用 node scripts/verify-package.mjs <解压后的包目录> 重复验证。打包不会替换正在运行的服务。
文档
目标压缩与命令审计
MySQL/MongoDB 目标可选择 zlib 压缩（默认关闭），通过协议协商启用，目标不支持时保持未压缩连接；连接测试显示实际协商结果。压缩仅作用于 serviceport 到目标服务一侧，直连和 SOCKS5 均适用。当前 SSH 库仅支持未压缩传输。
「命令审计」记录 MySQL SQL/预编译模板、MongoDB 请求、SSH exec、交互输入行和 SFTP 操作，可按网关/协议筛选并分页查看。内容加密保存，保留 7 天，每条最多 16 KiB，截断会标记。放行/拦截是网关决策，不表示目标执行成功。审计写入失败时不继续转发该命令。
不记录认证握手、SFTP 文件内容或命令输出。MySQL 二进制预编译执行记录 SQL 模板、statement ID 与参数包字节数，不展开参数值；MongoDB 文档序列批量正文不展开，只记录命令主体及总字节数。SSH 交互输入并非远端执行追踪：历史命令选择、光标编辑、脚本内部命令、全屏程序及密码提示输入无法可靠区分；需要严格远端执行审计时应配合服务器 auditd 等机制。