76 lines
8.1 KiB
Markdown
76 lines
8.1 KiB
Markdown
# linkport Windows 单 EXE
|
||
|
||
适用于 Windows x64 或 ARM64 的对应构建，无需安装 Go 或 Node.js。每个平台交付目录仅包含 `linkport.exe`，网页界面已嵌入程序。本说明保留在源码仓库，不再作为伴随文件输出。macOS／Linux 的构建与验证边界见 [跨平台支持](../../docs/platform-support.md)。
|
||
|
||
顶部版本入口及 `linkport.exe --version --json` 显示当前版本、Git 提交与构建时间。Kubernetes 出口内置 port-forward，无需安装 kubectl；目标服务可配置 kubeconfig 路径、context、命名空间与 Pod/Service/Deployment，详见 [Kubernetes](../../docs/kubernetes.md)。
|
||
|
||
## 启动
|
||
|
||
「代理」菜单独立维护通用出口；目标服务通过下拉框选择代理或直接连接。多个目标可复用同一代理。代理被引用时禁止删除，修改前先停止所有关联网关；旧目标的内联出口自动迁移为独立加密配置。
|
||
|
||
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 持久化](../../docs/single-file-storage.md)。
|
||
|
||
管理员登录密码不可查看，通过在程序目录运行 `.\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 文件内容及认证握手不记录。
|