LinkPort/docs/modules.md

serviceport 模块说明

本文按当前源码整理，帮助使用者理解功能，也帮助维护者找到修改入口。核对日期：2026-09-13。

1. 核心对象

对象	负责什么	典型配置	使用的账号
网关服务 Gateway	对客户端开放监听端口，认证客户端，执行访问策略，再转发请求	监听地址和端口、协议、目标引用、来源限制、连接上限	网关账号：客户端连接 serviceport 时填写
目标服务 Target	描述真正要访问的数据库、服务器或 HTTP 服务	目标地址和端口、TLS、目标账号、SSH 身份校验、出口引用	目标账号：serviceport 登录上游服务时使用
代理出口 Outbound	决定 serviceport 通过什么网络路径到达目标	直连、SOCKS5、SSH 跳板机、Kubernetes port-forward	出口凭据：登录代理或访问 Kubernetes 时使用
文件资产 Asset	集中保存可复用的文件凭据与证书	Kubeconfig、SSH 私钥、公钥列表、用户证书、TLS/CA 证书、其他文本配置	由目标、账号和出口按类型引用

一个目标可以被多个同协议网关复用，一个出口可以被多个目标复用。网关可以先保存而不关联目标，建立目标关联后才能启动业务监听。网关可以设置默认目标账号，也可以让不同网关账号分别映射到不同目标账号。

例如：客户端用网关账号 reporter 连接本机 MySQL 网关，网关选择目标账号 db_reader，通过 SSH 跳板机连接内网 MySQL。网关密码、数据库密码和跳板机密码是三组独立凭据。

2. 管理请求与业务流量的关系

flowchart LR
    UI[浏览器管理界面] --> API[internal/api 管理接口]
    API --> Store[internal/store 配置与审计存储]
    API --> Manager[internal/gateway 运行管理]
    Client[数据库或 SSH 等业务客户端] --> Manager
    Manager --> Protocol[internal/protocol 协议处理]
    Protocol --> Outbound[internal/outbound 网络出口]
    Outbound --> Target[真实目标服务]
    Protocol -. 命令审计与认证事件回调 .-> Manager
    Manager --> Store
    Alerts[internal/alerts 告警引擎] --> Manager
    Alerts --> Store

管理接口负责配置、权限和操作；业务客户端直接连接网关监听端口。协议模块通过 model.Handler 接口提供 Serve 和 Test，通过传入的 DialFunc 使用网络出口，通过上下文和回调上报审计及事件。

3. 启动、桌面与基础设施

下文源码链接均相对于本文所在目录，可直接点击定位。

模块 / 入口	职责	什么时候看这里
cmd/serviceport/main.go	主程序入口；读取环境配置、初始化密钥与数据库、注册协议、恢复健康检查和启用的网关、启动管理 HTTP 服务、处理退出信号和定期日志清理	修改启动流程、增加协议注册、调整服务生命周期
cmd/devcert/main.go	独立开发证书工具，调用证书模块生成本机测试证书	生成开发 TLS 材料
internal/desktop	Windows/macOS/Linux 本地模式；数据目录、数据库文件权限与进程锁、首次管理员设置和打开浏览器	排查本机启动、首次设置与跨平台运行
internal/localcert/cert.go	生成 localhost 开发 TLS 证书及私钥	调整开发证书生成规则；正式证书由部署者提供
internal/security/vault.go	AES-GCM 加解密、32 字节主密钥校验及安全随机令牌；用用途标识绑定密文	修改配置加密基础能力；个人登录密码校验在 store/store.go
internal/buildinfo/version.go	组织版本、提交、构建时间、Go 版本和平台信息	CLI、API 与界面版本展示
version.go、VERSION	根包嵌入默认版本值，供构建信息模块读取	更新项目版本
web/embed.go	将 Vite 构建出的 web/dist 嵌入 Go 程序并提供静态文件服务	排查打包后页面缺失；须先构建前端，再编译 Go

4. 数据模型：internal/model

模型层定义配置结构、合并规则、校验和协议公共接口，供 API、存储及运行层共同使用。

文件	负责什么
proxy.go	网关及运行时配置、网关账号和出口等公共结构、默认值、配置脱敏；定义 Handler、DialFunc、TestResult 等接口与结果类型
target.go	目标结构，将目标配置组合进运行时网关；GatewayOnly 去掉网关记录里的上游材料
target_account.go、target_auth.go	目标多账号、密码/空密码/SSH 私钥认证、支持协议的无认证模式、账号选择和凭据更新规则
gateway_account.go	网关多账号校验、稳定账号 ID 和编辑时保留已存秘密的规则
credential_lifecycle.go	凭据到期与提醒、目标账号引用校验、账号映射和运行时凭据有效性检查
outbound_profile.go、kubernetes.go	可共享的出口配置、出口合并校验，以及 Kubernetes 资源、命名空间和配置字段校验
validation.go	协议、地址、端口、来源范围、访问模式等公共配置校验
audit.go	命令审计结构与上下文回调，使协议模块可以上报命令而无需直接操作数据库

5. 管理接口：internal/api

业务接口统一位于 /api/v1/；/healthz 和 /readyz 是独立探针路径。API 校验会话或 Token 权限，进行输入校验，再调用存储或运行模块。

文件	接口 / 功能	负责什么
server.go	总路由、session、logout、version	服务状态、请求分发、来源与 CSRF 检查、认证和角色控制、配置操作串行协调
http_helpers.go	公共 HTTP 工具	请求大小限制、JSON 解码、统一响应和错误、来源地址提取
auth.go	login、reveal-password	登录限流、登录认证、查看秘密前的身份校验
tokens.go、token_response.go	tokens、Bearer Token 响应	Token 创建、列表、撤销、作用域判断；读写 JSON 响应清除敏感值
targets.go	targets	目标服务、目标账号、引用保护、连接测试和 SSH 目标身份确认
proxies.go	proxies	网关配置、目标关联、启停、状态及凭据查看入口
outbounds.go	outbounds	共享出口管理、目标引用保护及 SSH 跳板机测试
validation.go	保存配置的公共检查	可编辑字段、SSH 密钥等 API 层校验和辅助逻辑
commands.go、events.go	commands、events	命令审计与连接事件的筛选、分页、CSV 导出
connections.go	connections	列出活动业务连接、按连接 ID 主动断开
monitoring.go	monitoring	查询运行指标、发起目标健康检查、保存周期检查间隔
prometheus.go	metrics	将运行和健康状态输出为 Prometheus 文本指标
readiness.go	readyz	根据已绑定网关及监听器状态判断就绪；目标协议可用性由健康检查判断
alerts.go	alerts	告警查询、检查、确认和通知设置
configuration.go	configuration	加密配置导出、合并导入预览、提交、历史差异和恢复；导出包含全部资产文件与凭据；导入与恢复要求网关已停止
webdav_sync.go	configuration/webdav	WebDAV 脱敏设置、状态、手动同步及独立备份；禁止 API Token
templates.go	templates	脱敏配置模板的保存、列表、读取与删除

新增接口应放在对应领域文件中，server.go 保留路由和公共控制。页面隐藏按钮只是交互控制，真正的权限检查在后端执行。

6. 运行、协议与网络出口

6.1 网关运行：internal/gateway

文件	负责什么
manager.go	开关监听器、接受客户端连接、来源与连接数限制、调度协议 Handler、注入审计回调、停止时关闭连接
connections.go	记录连接 ID、来源、账号、认证状态及开始时间；支持单连接断开和证书到期信息
monitoring.go	连接及认证指标、手动健康探测、有限重试；周期以最多 4 个并发检查所有目标账号，取消时保留上次结果，稳定排序并恢复已保存间隔
failure.go	把底层错误转换成稳定的失败阶段和对外提示，供 API 与监控展示

6.2 协议处理：internal/protocol

当前注册 11 个协议类型，复用 9 个协议处理目录：SSH/SFTP 共用 sshproxy，HTTP/HTTPS 共用 httpproxy。TCP 端口映射不使用网关或目标账号，客户端直接向目标认证。

目录	协议类型	主要职责与当前边界
tcpproxy	tcp	双向 TCP 字节透传、写半关闭和取消清理；默认监听 0.0.0.0，复用来源/连接数限制与出口。不进行账号认证、TLS 终止、命令解析或只读控制；测试仅检查端口可达
mysqlproxy	mysql	MySQL 握手与账号替换、TLS、查询和预编译转发、zlib 压缩、SQL 审计、可选只读白名单；健康检查要求 COM_PING 响应。gateway.go 为入口，policy.go、audit.go、compression.go 分别处理策略、审计、压缩
mongoproxy	mongodb	MongoDB wire protocol、双端 SCRAM-SHA-256、压缩、命令审计和可选只读白名单；客户端需 directConnection=true。gateway.go 为入口，wire.go、policy.go、compression.go 分别处理报文、策略、压缩
pgproxy	pgsql	PostgreSQL 启动认证、上游 MD5/SCRAM、普通和扩展查询转发、SQL 审计；不代理独立 CancelRequest，不提供只读策略
sqlserverproxy	sqlserver	TDS 预登录、TLS、SQL 密码认证与账号映射、SQL Batch/RPC 审计；wire.go 处理报文细节，不支持 Windows/Kerberos 集成登录
redisproxy	redis	RESP 命令、AUTH/HELLO 账号映射、流水线、订阅推送和审计；面向 standalone，不自动处理 Cluster 重定向
rabbitproxy	rabbitmq	AMQP 0-9-1 PLAIN 认证映射、虚拟主机连接和帧转发；记录方法/通道元数据，不保存消息正文
sshproxy	ssh、sftp	SSH 握手、主机密钥验证、网关密码/公钥认证、目标密码/私钥认证、会话桥接和审计；sftp 类型仅开放 SFTP 子系统。ssh.go 为连接入口，audit.go 处理 exec、交互输入和文件操作审计
httpproxy	http、https	HTTP 请求转发、网关 Basic Auth、目标 Basic Auth 替换、TLS 和请求审计；不支持 CONNECT 或 WebSocket 升级
transport	协议公共工具	TCP/TLS 传输、连接转发、取消清理，以及协议共享的网关账号与来源检查；自身不注册为业务协议

只读策略目前由 MySQL/MongoDB 的协议模块实现。命令审计记录的是网关看到的请求和放行/拦截决定，不代表上游执行成功；详细边界见 只读策略 和 运维说明。

6.3 网络出口：internal/outbound

文件	负责什么
dial.go	按配置创建 DialFunc，选择直连、SOCKS5、SSH 转发或 Kubernetes 通道；SOCKS5 支持账号密码与远端 DNS
ssh.go	用密码连接 SSH 跳板机、核对主机指纹，建立 direct-tcpip 转发通道；提供跳板机连接测试
kubernetes.go	使用 client-go 读取集群配置、解析 Pod/Service/Deployment/StatefulSet、建立 port-forward，并在连接结束时清理资源；不依赖 kubectl

protocol/sshproxy 是客户端要使用的 SSH/SFTP 服务代理；outbound/ssh.go 是访问任意目标时可选的 SSH 跳板路径。出口故障不会自动回退直连。

7. 配置、审计与告警存储

7.1 持久化：internal/store

文件	负责什么
store.go	打开 SQLite、初始化表结构、组织迁移、公共存储操作与日志清理
portable.go	单 SQLite 主密钥、迁移和可移植存储；沿用 local_metadata 格式，不引入另一套 local_key 表
services.go	保存和查询网关、目标，解析关联目标与出口，维护引用关系
outbounds.go	共享出口加密保存、查询及引用统计
gateway_migration.go	迁移网关表的目标引用约束，使网关可以在未关联目标时独立保存
target_account_migration.go	将旧目标凭据转换为多账号结构，并维护引用一致性
identity.go	验证唯一的个人登录账号及身份修订号；密码重置使旧会话和 Token 失效
tokens.go	API Token 哈希、作用域、过期及撤销；当前文件也包含模板 CRUD，模板记录加密保存，保存及详情读取进行脱敏
templates.go	模板结构、版本和资源 ID 校验；模板允许缺少凭据，实际导入另做完整校验
backup.go	配置包、模板脱敏、口令加密备份、导入合并、引用校验和事务恢复；加密导出包含全部资产原文、文件名、引用及恢复所需凭据
webdav_sync.go、sync_bundle.go	WebDAV 加密设置、租约和同步基线；规范化快照、加密、冲突及完整替换
assets.go、api/assets.go	多类型文件资产加密存储、上传更新、目标/账号/代理引用保护和脱敏接口；更新后引用配置使用最新内容，资产纳入配置备份和历史
import_preview.go	共用导入合并规则，生成新增/覆盖/未变更列表、脱敏差异与配置修订标识；识别预览后的配置变更
config_history.go、config_diff.go	配置历史版本及字段对比；敏感值仅报告是否变化，账号按稳定 ID 比较
commands.go、audit_shards.go	命令审计写入、加密内容、跨日期查询和分页；按 UTC 日期分库、迁移旧日志、清理过期记录
event_shards.go	连接与管理事件的日期分库、迁移、跨日期读取和清理
monitoring.go	持久保存健康检查间隔；0 表示关闭，启用范围为 10–86400 秒
alerts.go	通知设置、告警状态、去重、确认、投递结果与保留期清理

配置与审计使用独立存储位置：配置数据库保存网关、目标、出口、用户、Token、模板和运维设置；audit/YYYY-MM-DD.sqlite 保存命令与事件，日志保留 7 天。密码哈希、Token 哈希与加密配置使用不同存储方式，并非将整个 SQLite 文件统一加密。

7.2 告警引擎：internal/alerts

engine.go 读取运行指标、健康结果、账号到期时间和证书到期信息，周期检查并维护告警状态。告警默认站内展示；管理员启用 Webhook 后，才会发送通知，可配置 HMAC-SHA256 签名并有限重试。HTTP 接口放在 api/alerts.go，告警记录放在 store/alerts.go。

7.3 WebDAV 同步与传输

internal/syncjob/engine.go 协调手动/定时多端同步、冲突选择和独立加密备份；internal/backup/webdav.go 负责 Basic/匿名认证、目录创建、GET 和条件 PUT。旧 S3 帮助代码只为历史兼容保留，当前页面、API 和调度不再使用。操作及升级说明见 WebDAV 同步备份。

8. 前端页面与公共状态：web/src

文件 / 组件	负责什么	用户在哪里使用
main.ts	创建 Vue 应用、加载 Element Plus 和样式	页面入口
App.vue	导航、登录、共享目标/网关/出口数据、概览、目标和网关主视图、编辑抽屉、批量操作及审计页面协调	管理后台主框架
SidebarNavigation.vue	按名称与关键词搜索有权访问的菜单，支持键盘选择和手机搜索面板	左侧菜单
Connections.vue	展示目标与网关关系；连线时展开目标账号，拖拽或点选完成多对一映射；支持启停、维护目标和断开关联	拖拽连线
TargetAccounts.vue	编辑目标多个账号、空密码/私钥及支持协议的无认证模式	目标配置
GatewayAccounts.vue	在独立账号页签编辑网关账号、目标账号映射、禁用、来源及账号策略	网关配置
SourceAllowlist.vue	单行编辑 IP/CIDR 列表，区分网关与账号作用范围，支持逗号分隔多项	网关配置与账号页签
AssetsManager.vue、AssetUpload.vue、AssetSelect.vue	多类型文件资产上传替换、引用展示及删除保护；按类型选择资产，目标/账号/代理按 ID 复用文件；KubeconfigUpload 为兼容包装	资产管理与配置编辑
CredentialExpiry.vue	复用的账号到期和提醒配置	目标/网关账号编辑
OutboundManager.vue	共享出口列表、创建编辑、引用关系、删除及 SSH 测试	代理菜单
OutboundFields.vue	复用的 SOCKS5、SSH 和 Kubernetes 出口表单	出口配置
OpsPanel.vue	运行指标、目标账号健康检查、周期设置，组合下方运维组件	监控运维
ActiveSessions.vue	活跃业务连接列表、刷新和管理员断开连接	监控运维 → 活跃会话
AlertsPanel.vue	告警列表、检查、确认和 Webhook 设置	监控运维 → 告警中心
ConfigurationManager.vue	加密配置导出（含全部资产文件）、导入预览和重新预览、确认导入、历史差异与恢复	配置管理 → 配置备份/历史
TemplateManager.vue	保存当前配置为模板、文件导入、查看编辑、导出、预览应用和删除	配置管理 → 配置模板
WebDAVSyncManager.vue	WebDAV 连接设置、手动及自动多端同步、独立加密备份、状态和冲突选择	多端同步
TokenManager.vue	选择作用域和有效期创建 Token、一次性显示密钥、查看与撤销	监控运维 → API Token
VersionInfo.vue	查询和展示构建版本信息	管理界面版本信息
composables/useApi.ts	封装 JSON 请求、会话 CSRF 更新、错误结果；仅在明确的 CSRF 拒绝后重试一次写请求	所有管理请求共用
composables/useAudit.ts	命令和事件筛选、翻页、导出，以及避免旧请求结果覆盖新筛选	命令审计、连接事件
composables/useConfigurationHistory.ts	管理历史资源选择、列表和差异请求时序，忽略过期响应，绑定恢复对象并防止重复提交	配置历史与恢复
composables/useWebDAVSync.ts	WebDAV 设置草稿、秘密保留/清除、同步备份请求及状态轮询	多端同步
composables/useMonitoring.ts	每 5 秒读取监控、请求去重、页面可见性与生命周期、刷新失败提示，以及检查间隔草稿保护	监控运维
domain/outbound.ts	统一出口类型名称及摘要文案	出口列表和引用展示
theme.ts、style.css	主题选择、浏览器偏好保存、跟随系统和全局响应式样式	全局外观

目前目标和网关主编辑流程仍在 App.vue。新增独立页面状态优先放入 composables，可复用视图优先拆为组件，避免继续把所有功能集中到 App.vue。

9. 构建、部署、测试和本地目录

入口 / 目录	负责什么
go.mod、go.sum	Go 模块与依赖版本、校验信息；当前固定 Go 1.25.0 以兼容 Vitess
web/package.json、web/package-lock.json	前端依赖、构建及 Playwright 命令和锁定版本
web/vite.config.ts、web/tsconfig.json、web/index.html	前端构建、TypeScript 检查和 HTML 模板
scripts/build.ps1、scripts/build.sh	开发构建入口，构建前端、执行 Go 测试并输出程序；Windows 脚本复用前端缓存，支持跳过测试、强制前端构建、自定义输出和阶段计时
start-dev.cmd、scripts/start-dev.ps1	Windows 项目/发布包启动入口；源码模式默认快速构建到临时产物目录，成功后停旧服务、备份并替换程序。FullCheck 附加 Go 全量测试，BuildOnly 只构建，RebuildWeb 强制前端重建
scripts/start-dev.test.ps1	使用临时项目和构建测试桩，验证启动参数传递、仅构建模式隔离与失败时不使用旧产物
package.cmd、scripts/package.ps1	Windows 发布打包、程序和证书工具构建、元信息、校验和、发布包验证及 ZIP 压缩
scripts/build-web.mjs	按依赖、源码、环境与产物摘要复用前端构建缓存；支持强制重建
scripts/build-lock.ps1	Windows 开发构建与发布打包共用的排他锁，防止前端生成和 Go 资源嵌入相互干扰；失败或退出后自动释放
scripts/version.ps1	读取版本和 Git 信息，生成构建注入参数
scripts/package.ps1、scripts/verify-package.mjs、scripts/verify-desktop.mjs	Windows 单 EXE 打包、原生发布包及本地模式验证；当前没有六目标 package.mjs 入口
Dockerfile、.env.example、packaging/windows	容器构建、部署配置示例及 Windows 发布说明；环境示例文件不会被程序自动加载
.drone.yml	Linux amd64 CI 测试、单文件构建与校验、版本归档及可选 IPFS 标签发布；真实运行仍须在 Drone 环境验证
deploy/ha	两个独立实例加 HAProxy 的部署示例；不提供内置复制、自动同步或会话迁移
scripts/test-matrix.ps1、scripts/test-matrix.sh	启动隔离 Docker 环境，运行真实 MySQL、MongoDB 和 SSH 集成矩阵
deploy/compose.test.yml、deploy/mongo、deploy/ssh、deploy/fixtures	矩阵使用的容器、MongoDB 副本集初始化、SSH 配置和测试辅助服务
internal/testutil	后端测试共用的网络出口等辅助设施；不属于生产功能模块
各 Go 目录下的 *_test.go	本模块单元、回归和集成测试；带真实服务环境要求的用例需要相应测试环境
web/tests、web/playwright.config.ts	页面与接口交互回归；start-server.mjs 使用临时数据启动开发模式和认证模式实例，通过 SERVICEPORT_E2E_BINARY 指定被测程序
data/	项目本地运行数据：SQLite、audit、TLS 和 Windows 主密钥材料；保留并按完整目录备份
bin/	程序、发布包、验证产物、构建缓存与完整备份，见 输出目录
web/dist/、web/node_modules/、web/test-results/、web/playwright-report/	前端产物、依赖和测试结果
vendor/	Go 第三方依赖源码副本；不是项目业务模块，当前保留本地、未纳入上次提交

验证时先使用 Go 1.25.0 运行后端测试与 vet，再完成前端构建，最后构建包含最新页面的程序并运行 Playwright。Vite 正在替换 dist 时不要同时编译嵌入该目录的 Go 程序。真实服务矩阵、本地协议测试桩和浏览器流程测试覆盖不同层次，不能互相代替。

10. 想改某个功能，从哪里开始

修改目标	建议定位顺序
增加一种业务协议	model 协议校验 → protocol 新目录实现 Handler → cmd/serviceport 注册 → API 输入/测试能力 → 前端协议选项与表单 → 协议及浏览器测试
增加一种代理出口	model 出口结构及校验 → outbound Dialer 分支 → API 出口保存/测试 → OutboundFields 与 domain/outbound → 出口测试
增加账号字段或改变映射	model 账号结构/合并校验 → store 持久化与旧数据迁移 → API → TargetAccounts/GatewayAccounts → 认证、脱敏和迁移回归
调整导入导出或历史恢复	store/backup、import_preview、config_history、config_diff → api/configuration → ConfigurationManager；同步检查脱敏与引用完整性
调整角色或 Token 权限	store/users、tokens → api/server、users、tokens、token_response → AdminUsers/TokenManager → 权限与秘密隔离回归
增加监控指标或告警	gateway/monitoring、connections → alerts/engine 与 store/alerts → api/monitoring、prometheus、alerts → OpsPanel/AlertsPanel
增加命令审计能力	protocol 对应协议解析 → model.AuditCommand → store/commands → api/commands → useAudit 与审计页面
排查启动或打包	cmd/serviceport → desktop 或 buildinfo → scripts 构建/验证入口；先确认实际数据目录与程序版本

11. 相关文档

• README：项目入口、支持能力、运行环境和常用命令。
• 网关账号与运维：多账号、监控、告警、备份、模板、Token 与验证范围。
• 目标账号：目标账号管理与网关选择。
• SSH 连接测试：SSH 出口测试与失败信息。
• 只读策略：MySQL/MongoDB 白名单与能力边界。
• Kubernetes：集群配置、资源选择、转发与权限要求。
• 测试说明：测试环境与真实服务验证边界。
• 高可用部署：独立节点和外部负载均衡示例。
• Drone/IPFS 发布：CI 发布配置说明；使用时同时检查当前流水线入口。
• 开发计划：历史设计与阶段计划，其中旧协议数量和“未包含”列表不作为当前功能清单。