Ubuntu 24.04 安装 trdsql 1.2.3 指南

目标：在 Ubuntu 24.04 服务器上从零安装 trdsql v1.2.3，覆盖官方二进制包、go install 在线构建、源码 make build 三种方案的全流程（下载→校验→安装→验证→卸载），已在 Ubuntu 24.04.5 LTS（x86_64）+ PostgreSQL 16.15 + SQLite 3.45.1 环境实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（PRETTY_NAME="Ubuntu 24.04.5 LTS"），架构 x86_64，主机名 trdsql-server，内网地址 10.89.56.2/24
• 安装对象：trdsql v1.2.3（GitHub Releases 最新稳定版，发布于 2026-05-29，releases.atom 实查，查询日期 2026-11-03）
• Go 环境：apt 安装 golang-go 得 go1.22.2 linux/amd64（方案 B/C 用，GOTOOLCHAIN=auto 会自动补齐所需工具链）
• 数据库后端（供后续功能验证连接）：PostgreSQL 16.15 数据库服务器 db-server（10.89.56.3，演示账号 root/q1w2e3r4，库 trdsql）；SQLite 3.45.1（apt sqlite3）
• 基础工具：wget、unzip、git、gcc、make（apt 官方源直连安装成功，未降级）
• 网络渠道实测：GitHub Releases 二进制官方源直连可用；go install 的官方模块代理 proxy.golang.org 超时，已降级国内源 goproxy.cn；源码 git clone GitHub 直连超时，已降级走代理——各步骤均有 ⚠️ 注明

二、前置条件

trdsql 是单二进制 CLI，方案 A（官方二进制）无任何运行时依赖；方案 B/C 需要 Go 工具链。先装基础工具：

apt-get update && apt-get install -y wget unzip ca-certificates
# 方案 B/C 额外：
apt-get install -y golang-go
# 方案 C 额外：
apt-get install -y git gcc make

实测验证：

$ go version
go version go1.22.2 linux/amd64

💡 说明：gcc 仅在源码编译时必需——trdsql 默认用 CGO 的 go-sqlite3 作内嵌查询引擎；官方 Releases 预编译包已解决此依赖，纯二进制安装不需要 gcc。

三、版本选型说明

v1.2.3 为当前最新稳定版（releases.atom 实查，查询日期 2026-11-03），近 6 个版本节奏：

Linux amd64 资产命名规则为 trdsql_v<版本>_linux_amd64.zip（注意带 v 前缀、zip 格式而非 tar.gz；v1.2.3 发布未附 checksums 清单文件，校验值以本地留存的 sha256 为准，见 4.2）。发布页同时提供 386/amd64/arm64/arm-5/6/7/mips/mips64/mipsle 等 Linux 架构与 darwin/windows 包，按需选择。

四、方案 A：官方二进制包安装（推荐）

4.1 下载发布包

从 GitHub Releases 官方源直接下载（实测官方源可用，未降级）：

cd /opt/work
wget https://github.com/noborus/trdsql/releases/download/v1.2.3/trdsql_v1.2.3_linux_amd64.zip

实测输出（节选，实测首尾）：

 10100K .......... .......... .......... .......... .......... 99% 62.0M 0s
 10150K .......... .......... .....                           100%  424M=1.2s

$ ls -la trdsql_v1.2.3_linux_amd64.zip
-rw-r--r-- 1 root root 10419941 May 29 05:43 trdsql_v1.2.3_linux_amd64.zip

4.2 校验与解压

v1.2.3 发布页无 checksums.txt 资产，落地后先记录 sha256 留档比对：

$ sha256sum trdsql_v1.2.3_linux_amd64.zip
812d1e81f98b6a8b6e7c5f1d8ef8e451d6ea75a14bd8a72c1c2334d7c78d9305  trdsql_v1.2.3_linux_amd64.zip

$ unzip -o trdsql_v1.2.3_linux_amd64.zip
Archive:  trdsql_v1.2.3_linux_amd64.zip
   creating: trdsql_v1.2.3_linux_amd64/
  inflating: trdsql_v1.2.3_linux_amd64/LICENSE
  inflating: trdsql_v1.2.3_linux_amd64/trdsql
  inflating: trdsql_v1.2.3_linux_amd64/config.json.sample
  inflating: trdsql_v1.2.3_linux_amd64/README.md

包内除二进制外还附带 LICENSE、README.md 与 config.json.sample（命名连接配置样例），后者是配置篇（见本专栏《trdsql 1.2.3 配置参数详解》篇）的官方模板，无需另行联网获取。

4.3 安装到系统路径并验证

$ cd trdsql_v1.2.3_linux_amd64 && sha256sum trdsql
642cdbab1fbee3a2b7dc68d757c095464e094c2a4a30b57bac0a2111e206a8b8  trdsql

$ install -m 755 trdsql /usr/local/bin/trdsql

$ which trdsql
/usr/local/bin/trdsql

$ trdsql -version
trdsql version v1.2.3

trdsql -version 回显 v1.2.3 即安装成功。trdsql 是一次性命令工具，无常驻进程、无需 systemd 托管，装完即可在任何 shell 直接使用。

五、方案 B：go install 在线构建安装

适合需要跟随源码最新版、或统一用 Go 工具链管理安装的场景。

5.1 安装 Go 环境并确认工具链策略

$ apt-get install -y golang-go && go version
go version go1.22.2 linux/amd64

$ go env GOTOOLCHAIN GOPROXY
auto
https://proxy.golang.org,direct

⚠️ 版本要求：trdsql README §1.1.1 声明源码编译需 go 1.25 或更高。Ubuntu 24.04 的 apt go 为 1.22.2，但 GOTOOLCHAIN=auto（默认值）会在构建时自动下载满足要求的工具链（见 5.2 实测），无需手动升级 Go。

5.2 执行安装（含模块代理降级实录）

先按默认官方模块代理尝试：

$ go install github.com/noborus/trdsql/cmd/trdsql@v1.2.3
go: github.com/noborus/trdsql@v1.2.3: github.com/noborus/trdsql@v1.2.3: Get "https://proxy.golang.org/github.com/noborus/trdsql/@v/v1.2.3.info": dial tcp 142.251.33.209:443: i/o timeout

⚠️ 网络说明：官方模块代理 proxy.golang.org 当时不可用（i/o timeout），已降级国内源 goproxy.cn，实测可用：

$ GOPROXY=https://goproxy.cn,direct go install github.com/noborus/trdsql/cmd/trdsql@v1.2.3
go: github.com/noborus/trdsql@v1.2.3 requires go >= 1.25.0; switching to go1.26.10
go: downloading github.com/dsnet/compress v0.0.1

注意安装路径：trdsql 仓库根包是库（library），CLI 入口在 cmd/trdsql。若误写 go install github.com/noborus/trdsql@v1.2.3 会报：

package github.com/noborus/trdsql is not a main package

5.3 验证

$ ls -la ~/go/bin/
total 17572
drwxr-xr-x 2 root root     4096 Nov  3 04:31 .
drwxr-xr-x 4 root root     4096 Nov  3 04:31 ..
-rwxr-xr-x 2 root root 17982776 Nov  3 04:31 trdsql

$ ~/go/bin/trdsql -version
trdsql version devel

⚠️ 说明：go install 构建的版本号回显 devel——版本号由发布流水线经 -ldflags 注入，源码默认值是 devel；go install 不带注入，属正常现象，不代表装错版本（锁定 v1.2.3 靠 @v1.2.3 模块版本）。若需与方案 A 一致的版本回显，用方案 C 的 make build（Makefile 内置 ldflags）。另注意 ~/go/bin 默认不在 PATH，需 export PATH=$PATH:~/go/bin 或把二进制 install 到 /usr/local/bin。

六、方案 C：源码 make build 编译安装

6.1 获取源码（含直连超时降级实录）

先按 GitHub 官方源直连：

$ git clone --depth 1 --branch v1.2.3 https://github.com/noborus/trdsql.git trdsql-src
Cloning into 'trdsql-src'...
fatal: unable to access 'https://github.com/noborus/trdsql.git/': Failed to connect to github.com port 443 after 132708 ms: Couldn't connect to server

⚠️ 网络说明：GitHub 直连克隆当时不可用（443 连接超时），已改走代理 192.168.1.72:7897，实测可用：

$ git -c http.proxy=http://192.168.1.72:7897 clone --depth 1 --branch v1.2.3 https://github.com/noborus/trdsql.git trdsql-src
Cloning into 'trdsql-src'...

6.2 编译并验证

$ cd trdsql-src && grep -n -A2 "^build:" Makefile
39:build: $(TARGET_NAME)
40-
41-$(BINARY_NAME): $(SRCS)
42-	$(GOBUILD) -o $(BINARY_NAME) ./cmd/$(TARGET_NAME)

$ GOPROXY=https://goproxy.cn,direct make build
go build -tags "sqlite_math_functions" -ldflags="-X github.com/noborus/trdsql.Version=v1.2.3" -o trdsql ./cmd/trdsql
go: downloading go1.25.0 (linux/amd64)

$ ls -la trdsql && ./trdsql -version
-rwxr-xr-x 1 root root 17582208 Nov  3 04:34 trdsql
trdsql version v1.2.3

make build 自动带上 -tags sqlite_math_functions（启用 SQLite 数学函数扩展）与 -ldflags 版本注入，产物回显真实版本号 v1.2.3；构建目标为 ./cmd/trdsql，同样印证 5.2 的"根包非 main"。make install 则等价 go install ./cmd/trdsql。

七、方案对比与选择建议

选择建议：生产与日常一律方案 A（下载即用、版本可辨）；需要 @latest 滚动更新且不在意 devel 回显用 B；要审计构建、加自定义编译 tag 或二次开发用 C。

八、配置说明

• trdsql 无强制配置文件，开箱即用（默认内嵌 SQLite3 引擎、内存临时库）。
• 可选的命名连接配置文件为 JSON 格式（非 TOML）：默认位置 ~/.config/trdsql/config.json（Windows 为 %APPDATA%\trdsql\config.json），或用 -config 文件 显式指定；发布包内 config.json.sample 即官方样例。字段含义、-db/-dblist 用法与生产模板详见本专栏《trdsql 1.2.3 配置参数详解》篇。
• 与安装相关的两个 Go 环境变量：GOTOOLCHAIN（auto=允许自动下载新工具链，方案 B/C 依赖它补 go≥1.25）、GOPROXY（官方 proxy.golang.org 不可用时改 https://goproxy.cn,direct）。
• 数据后端连接（PostgreSQL/MySQL）不属于 trdsql 安装配置，由目标数据库服务器自身管理；本文实测连接的 PostgreSQL 16.15 服务器演示账号 root/q1w2e3r4。

九、常见问题

Q1： go install github.com/noborus/trdsql@v1.2.3 报 package github.com/noborus/trdsql is not a main package？

A： 根包是库，CLI 在子目录。正确写法：go install github.com/noborus/trdsql/cmd/trdsql@v1.2.3（5.2 实测）。

Q2： go install 后提示 requires go >= 1.25.0; switching to go1.26.10，是否失败？

A： 不是失败。GOTOOLCHAIN=auto 检测到模块要求高于本机 go1.22.2，自动下载 go1.26.10 工具链继续构建，属预期行为（5.2 实测）。若公司环境禁止自动下载工具链，可设 GOTOOLCHAIN=local，此时需先把 Go 升到 ≥1.25。

Q3： go install 装的二进制在 /usr/local/bin 找不到？

A： go install 产物在 ~/go/bin/trdsql（5.3 实测 ls 回显），该目录默认不在 PATH。手动 install -m 755 ~/go/bin/trdsql /usr/local/bin/ 或加 PATH。

Q4： 方案 A 下载 GitHub Releases 慢或失败怎么办？

A： 本文实测官方源直连可用（4.1，1.2 秒完成）。若遇超时可按降级链处理：先试国内加速站点，仍不行则 wget -x http://192.168.1.72:7897 <URL> 走代理。

Q5： 源码构建报 CGO 相关错误？

A： trdsql 默认构建依赖 CGO 的 go-sqlite3，需 gcc 在位（方案 C 已装）。官方也支持 CGO_ENABLED=0 构建（改用纯 Go 的 sqlite 实现，README §1.6），届时 -driver 需选 sqlite 而非 sqlite3，性能略降。

十、卸载与清理

$ rm -f /usr/local/bin/trdsql
$ trdsql -version
bash: line 1: trdsql: command not found
exit=127

# go install 产物卸载（实测）
$ rm -f ~/go/bin/trdsql

# 可选清理
rm -rf ~/.config/trdsql          # 命名连接配置
rm -rf /opt/work/trdsql-src      # 方案 C 源码树

卸载仅删二进制与配置目录即可；trdsql 无系统级服务、无数据库残留（临时表在进程退出时随内存库消失，写入 SQLite 文件的表数据归用户数据文件，按需删除）。

十一、参考链接

• 官方安装文档：https://github.com/noborus/trdsql#install （README §1，查询日期 2026-11-03）
• Releases 发布页：https://github.com/noborus/trdsql/releases/tag/v1.2.3
• Go 模块页：https://pkg.go.dev/github.com/noborus/trdsql
• goproxy.cn 国内模块代理：https://goproxy.cn
• 站内：《trdsql 介绍与选型指南》（第一章环境信息与版本溯源）