LinkPort/packaging/windows

linkport Windows 单 EXE

适用于 Windows x64 或 ARM64 的对应构建，无需安装 Go 或 Node.js。每个平台交付目录仅包含 linkport.exe，网页界面已嵌入程序。本说明保留在源码仓库，不再作为伴随文件输出。macOS／Linux 的构建与验证边界见 跨平台支持。

顶部版本入口及 linkport.exe --version --json 显示当前版本、Git 提交与构建时间。Kubernetes 出口内置 port-forward，无需安装 kubectl；目标服务可配置 kubeconfig 路径、context、命名空间与 Pod/Service/Deployment，详见 Kubernetes。

启动

「代理」菜单独立维护通用出口；目标服务通过下拉框选择代理或直接连接。多个目标可复用同一代理。代理被引用时禁止删除，修改前先停止所有关联网关；旧目标的内联出口自动迁移为独立加密配置。

1. 将 linkport.exe 放在要使用的目录并双击。程序按下述顺序查找数据；从其他目录调用 EXE 或改变快捷方式的“起始位置”会改变当前目录候选。交付文件无需解压，也不依赖启动脚本。
2. 浏览器自动打开；开发阶段默认免登录，直接进入控制台。
3. 先添加目标服务，再创建网关并选择关联目标；多个网关可复用一个目标。以后双击即用。右上角支持浅色、深色、海蓝和跟随系统主题。

默认管理端口由系统自动分配，启动窗口显示 http://127.0.0.1:<实际端口> 并自动打开浏览器；每次启动端口可能不同。保持程序窗口运行，按 Ctrl+C 停止服务；关闭窗口也会结束进程。不要重复启动多个窗口。显式配置的端口被占用或初始化失败时，窗口显示错误并等待 Enter，不会闪退。浏览器未自动打开时，可复制窗口中的管理页面地址；开启认证后的首次设置须使用包含一次性 token 的完整地址。

管理员登录（可选）

默认 LINKPORT_AUTH_ENABLED=false，仅允许本机管理，无需创建管理员。要启用登录，在 PowerShell 设置 $env:LINKPORT_AUTH_ENABLED = 'true' 后运行 .\linkport.exe；首次会打开管理员设置页面，已有账号则直接登录。开启认证后密码仍使用 bcrypt 保存。

数据和备份

Windows 本地模式统一按以下顺序选择数据库：

1. 非空 LINKPORT_DATA：使用指定文件，相对路径以当前工作目录为基准；不再搜索其他位置。
2. 当前工作目录下已有的 data\linkport.sqlite。
3. %APPDATA%\linkport\linkport.sqlite 中已有的数据库。
4. 都没有时，在当前工作目录下新建 data\linkport.sqlite；不因 AppData 目录存在就把新库放到那里。

两个库都存在时当前目录优先，不合并、不搬移、不删除另一个库。选中的数据库被占用、无法访问、内容损坏或旧库缺少迁移密钥时直接失败，不另建空库。AppData 环境不可用且没有显式路径时仍可使用当前目录。不再提供手动主密钥运行模式。

单 EXE 交付不包含源码仓库的 start-dev.cmd 和 scripts/start-dev.ps1。直接运行 EXE 不执行这些脚本的升级备份流程；替换旧版本前，应停止旧服务并备份完整数据目录，再运行新 EXE。源码目录的启动脚本仍保留原有查询数据路径、停服、持锁备份和启动行为。

可执行 .\linkport.exe data-path 查看最终路径，该命令不初始化数据。旧库须先停服并备份完整旧目录，再用新版的 migrate-data 离线迁移（DPAPI 迁移须在原用户/机器下）；旧外部密钥库使用 migrate-key 交互输入原密钥。迁移后不要用旧程序打开新库，回退应恢复完整旧备份。

• linkport.sqlite：管理员、配置、主密钥、命令/输出审计、连接事件及自动 TLS 身份。
• SQLite 运行时可能产生 WAL/SHM 临时文件，不能删除或在备份时忽略；正常停服后可只复制主文件。
• 旧 audit/、master-key.dpapi、tls/ 仅作为迁移输入保留，不自动删除；新库不再生成这些文件或 desktop.lock。

迁移完成并正常停服后，只复制 SQLite 到新目录即可跨机器运行；旧目录可归档。主密钥与密文同库，取得文件就能恢复凭据，请按敏感材料保护。完整迁移步骤、外部文件引用的边界见 单 SQLite 持久化。

管理员登录密码不可查看，通过在程序目录运行 .\linkport.exe reset-password 交互重置（先停止服务）。目标服务、网关、SOCKS5 密码可分别查看；开启认证时需要再次输入管理员密码，开发模式直接查看。

数据库 TLS

自动证书有效期一年，覆盖 localhost、127.0.0.1 和 ::1，与私钥一起保存在 SQLite。停止服务后执行 .\linkport.exe export-ca，将标准输出的公开 PEM 保存并导入 MySQL/MongoDB 客户端信任；私钥不会输出。SSH 使用自身主机密钥。

正式域名或证书轮换可通过 LINKPORT_TLS_CERT 和 LINKPORT_TLS_KEY 显式指定受信任证书；这些自定义外部文件仍由部署者管理。不要删除 SQLite 内部元数据来轮换证书。

高级配置

不再读取 LINKPORT_MASTER_KEY，也不再提供 generate-key。启用 LINKPORT_AUTH_ENABLED=true 后，本地可通过首次设置页面或环境变量创建账号；非回环远程部署必须开启认证，并在首次启动提供 LINKPORT_ADMIN_USER / LINKPORT_ADMIN_PASSWORD。

程序不自动读取 .env；.env.example 是环境变量参考，LINKPORT_DATA 留空表示自动选择。直接运行程序和 start-dev.cmd 均保留显式设置的数据路径；相对路径以程序运行时的工作目录为基准，绝对路径保持指定位置。LINKPORT_HTTP_ADDR 必须使用回环 IP，默认 127.0.0.1:0，由系统分配空闲端口。需要稳定地址时可设为 127.0.0.1:8080 等固定端口，直接运行程序和 start-dev.cmd 均尊重该设置；LINKPORT_NO_BROWSER=1 禁止自动打开浏览器。

多路径验证记录

2026-09-20：路径与 CLI 单元测试、源码/发布启动脚本 fixture 测试、Go vet、前端生产构建，以及新 EXE 的 Edge 桌面验收通过。桌面验收使用隔离工作目录和隔离 AppData，验证旧库复用、原账号登录、密钥和 TLS 保持，不读取实际用户数据。全量回归并非全部通过：Go 集群发现 fixture 失败；Playwright 为 77 通过、3 失败、8 未运行，失败涉及小屏账号编辑和 URL/资源导航用例，详见仓库中的 docs/testing.md。本次没有部署到实际数据目录。

使用说明

• 六类目标服务支持直连、SOCKS5 或 SSH 转发出口；网关引用目标，MySQL、MongoDB 网关默认读写，可选只读。
• SSH 保存配置后需探测主机指纹，通过可信渠道核对并确认后才能启动。
• 修改目标前先停止所有引用网关；被引用的目标不能删除。修改网关前先停止该网关，停止会断开已有客户端。
• 管理服务默认仅本机访问。远程管理必须设置 LINKPORT_AUTH_ENABLED=true，并配置 HTTPS 反向代理。

不再附带 devcert.exe、ZIP、校验清单或配置示例；本地模式由主程序自动生成证书。版本元数据保存在 EXE 中，打包日志打印 EXE 的 SHA-256，可通过 PowerShell Get-FileHash .\linkport.exe -Algorithm SHA256 核对。

真实 MySQL/MongoDB 多版本和 OpenSSH 的 Docker 兼容矩阵仍待实际环境验证，详见 docs/testing.md。

压缩与命令记录

在目标配置中可为 MySQL/MongoDB 开启 zlib 压缩，目标不支持时不压缩，连接测试显示实际算法；SSH 暂不支持压缩。

「命令审计」查看 SQL、MongoDB、SSH exec/交互输入及 SFTP 操作，支持按网关、协议筛选，内容加密保存 7 天。每条最多 16 KiB，超出标记截断。放行不表示目标执行成功；交互输入不等同远端实际执行命令，可能含程序输入。预编译 SQL 的参数值、MongoDB 批量文档序列正文、SFTP 文件内容及认证握手不记录。