LinkPort/docs/modules.md

# linkport 模块说明

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

全模块重构的模式、扩展规则、实际拆分与保留清单见 [设计模式与扩展边界](architecture-patterns.md)。

## 1. 核心对象

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

一个目标可以被多个同协议网关复用，一个网络代理可以被多个目标或 TCP 纯转发网关引用。「代理管理」独立维护 Kubeconfig、SSH、SOCKS5 和 sing-box，类型在创建表单顶部直接选择；文件仅作为凭据保留。普通协议网关的每个网关账号一对一选择目标账号后才能启动，并沿用目标的代理；Redis、MongoDB 和 TCP 的空账号也作为明确映射端点。TCP 纯转发可用 `tcpForward.mode="proxy"` 直接引用网络代理。详见 [网络代理管理](network-proxies.md)。

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

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

```mermaid
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/linkport/main.go](../cmd/linkport/main.go) | 组合根；准备数据锁与存储、创建协议工厂和运行管理器，协调命令与服务生命周期 | 修改启动编排 |
| [commands.go](../cmd/linkport/commands.go)、[bootstrap.go](../cmd/linkport/bootstrap.go)、[management.go](../cmd/linkport/management.go) | 独立/维护命令分派、TLS 与网关恢复、管理 HTTP/桌面/信号/定期清理 | 调整命令或运行生命周期 |
| [cmd/devcert/main.go](../cmd/devcert/main.go) | 独立开发证书工具，调用证书模块生成本机测试证书 | 生成开发 TLS 材料 |
| [internal/desktop](../internal/desktop) | Windows/macOS/Linux 本地模式；数据目录、数据库文件权限与进程锁、首次管理员设置和打开浏览器 | 排查本机启动、首次设置与跨平台运行 |
| [internal/localcert/cert.go](../internal/localcert/cert.go) | 生成 localhost 开发 TLS 证书及私钥 | 调整开发证书生成规则；正式证书由部署者提供 |
| [internal/security/vault.go](../internal/security/vault.go) | AES-GCM 加解密、32 字节主密钥校验及安全随机令牌；用用途标识绑定密文 | 修改配置加密基础能力；个人登录密码校验在 store/store.go |
| [internal/buildinfo/version.go](../internal/buildinfo/version.go) | 组织版本、提交、构建时间、Go 版本和平台信息 | CLI、API 与界面版本展示 |
| [version.go](../version.go)、[VERSION](../VERSION) | 根包嵌入默认版本值，供构建信息模块读取 | 更新项目版本 |
| [web/embed.go](../web/embed.go) | 将 Vite 构建出的 web/dist 嵌入 Go 程序并提供静态文件服务 | 排查打包后页面缺失；须先构建前端，再编译 Go |

## 4. 数据模型：internal/model

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

| 文件 | 负责什么 |
| --- | --- |
| [proxy.go](../internal/model/proxy.go) | 网关运行时配置快照及出口、SSH 公共配置结构 |
| [runtime.go](../internal/model/runtime.go) | Handler、DialFunc、EventFunc、TestResult 等协议运行契约 |
| [target.go](../internal/model/target.go) | 目标结构，将目标配置组合进运行时网关；GatewayOnly 去掉网关记录里的上游材料 |
| [target_account.go](../internal/model/target_account.go)、[target_auth.go](../internal/model/target_auth.go) | 目标多账号、密码/空密码/SSH 私钥认证、支持协议的无认证模式、账号选择和凭据更新规则 |
| [gateway_account.go](../internal/model/gateway_account.go) | 网关账号结构、选择与目标映射、权限上限、多账号校验、稳定 ID 和编辑时保留已存秘密的规则 |
| [credential_lifecycle.go](../internal/model/credential_lifecycle.go) | 凭据到期与提醒、目标账号引用校验、账号映射和运行时凭据有效性检查 |
| [outbound_profile.go](../internal/model/outbound_profile.go)、[sing_box.go](../internal/model/sing_box.go)、[kubernetes.go](../internal/model/kubernetes.go) | 可共享的出口配置与合并校验；sing-box 单对象、大小、复杂度和宿主能力限制；Kubernetes 资源、命名空间和配置字段校验 |
| [validation.go](../internal/model/validation.go) | 协议、地址、端口、来源范围、访问模式等公共配置校验 |
| [audit.go](../internal/model/audit.go) | 命令审计结构与上下文回调，使协议模块可以上报命令而无需直接操作数据库 |

## 5. 管理接口：internal/api

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

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

新增接口应放在对应领域文件中，`server.go` 协调公共控制，`routes.go` 明确路由及锁边界。页面隐藏按钮只是交互控制，真正的权限检查在后端执行。

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

### 6.1 网关运行：internal/gateway

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

### 6.2 协议处理：internal/protocol

通过 [handlers.go](../internal/protocol/handlers.go) 的 `NewHandlers` 工厂注册 11 个协议类型，复用 9 个协议处理目录：SSH/SFTP 共用 sshproxy，HTTP/HTTPS 共用 httpproxy。每次工厂调用返回独立的注册表。TCP 端口映射不使用网关或目标账号，客户端直接向目标认证。

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

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

### 6.3 网络出口：internal/outbound

| 文件 | 负责什么 |
| --- | --- |
| [dial.go](../internal/outbound/dial.go)、[strategy.go](../internal/outbound/strategy.go) | 工厂选择直连、SOCKS5、SSH、sing-box 或 Kubernetes 策略；公共装饰器按调用校验选项、设置建连期限并返回 DialFunc，失败不回退直连 |
| [socks5.go](../internal/outbound/socks5.go) | SOCKS5 握手、认证与目标协商；保留目标域名、诊断阶段和取消清理 |
| [ssh.go](../internal/outbound/ssh.go) | 用密码连接 SSH 跳板机、核对主机指纹，建立 direct-tcpip 转发通道；提供跳板机连接测试 |
| [singbox.go](../internal/outbound/singbox.go) | 定位外部 binary、生成私有 loopback SOCKS5 运行配置、执行 10 秒 `check`、按规范化 outbound 共享 `run` 子进程，并记录独立启动/本地协商阶段；不嵌入 sing-box module |
| [kubernetes.go](../internal/outbound/kubernetes.go) | 使用 client-go 读取集群配置、解析 Pod/Service/Deployment/StatefulSet、建立 port-forward，并在连接结束时清理资源；不依赖 kubectl |

`protocol/sshproxy` 是客户端要使用的 SSH/SFTP 服务代理；`outbound/ssh.go` 是访问任意目标时可选的 SSH 跳板路径。sing-box 是 linkport 管理的外部子进程，发布包不捆绑它。所有出口故障都不会自动回退直连。

### 6.4 集群发现：internal/cluster

[cluster.go](../internal/cluster/cluster.go) 负责校验、节点遍历、拓扑筛选和目标选择；[strategies.go](../internal/cluster/strategies.go) 集中六种协议探测策略，`redis.go` 与 `databases.go` 保留协议实现。遍历接受探测函数，便于用 fixture 验证取消、节点上限和 Sentinel 凭据切换。

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

### 7.1 持久化：internal/store

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

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

### 7.2 告警引擎：internal/alerts

[engine.go](../internal/alerts/engine.go) 编排周期检查、状态持久化和投递重试；[conditions.go](../internal/alerts/conditions.go) 评估健康、认证窗口、账号与证书到期规则；[notifier.go](../internal/alerts/notifier.go) 适配 Webhook，保留 HMAC-SHA256、5 秒超时与禁重定向。[repository.go](../internal/alerts/repository.go) 声明消费者需要的存储端口，条件更新与去重仍由 Store 负责。手动检查不发送通知，启用 Webhook 后周期投递最多尝试三次。HTTP 接口放在 api/alerts.go，告警记录放在 store/alerts.go。

### 7.3 WebDAV 同步与传输

[internal/syncjob/engine.go](../internal/syncjob/engine.go) 管手动/定时调度、锁、租约、取消及完成记录；[transfer.go](../internal/syncjob/transfer.go) 管同步基线、冲突选择和独立 JSON 备份，依赖消费者侧 Repository 与 [ObjectStore](../internal/backup/object_store.go) 条件对象存储接口。WebDAV 适配器复用 [webdav.go](../internal/backup/webdav.go) 的 Basic/匿名认证、目录创建、GET 和条件 PUT。S3 设置存储已删除，当前页面、API 和调度不使用 S3；本次未删除独立的 S3 传输帮助代码。操作及格式说明见 [WebDAV 同步备份](webdav-sync.md)。

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

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

App.vue 协调目标和网关编辑、导航与提交；草稿构造和载荷规则归 domain，独立异步状态归 composables，可复用视图归组件。全模块的模式及扩展方式见 [设计模式与扩展边界](architecture-patterns.md)。

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

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

## 11. 相关文档

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