Ubuntu 22.04 安装 TextQL 2.0.3 指南
在 Ubuntu 22.04.5 LTS 上经 apt 发行包（2.0.3-4build1）、go install 伪版本、master 源码构建三条途径安装 TextQL 2.0.3 的实测记录，含 -sqlfile 有无差异、版本串注入、GitHub 直连失败降级代理与 make test 失败排障
Ubuntu 22.04 安装 TextQL 2.0.3 指南
目标：在 Ubuntu 22.04.5 LTS 服务器上把 TextQL 2.0.3 装到可用状态。TextQL 的 GitHub release 停在 2015 年且不提供任何 Linux 二进制，但 Ubuntu universe 有发行包、Go 模块可直取 master、源码可自构建——本文实测三条安装途径（apt 发行包 / go install / 源码构建），讲清各途径产物在
-sqlfile与版本串上的差异，并沉淀 GitHub 直连失败走代理降级、make test失败绕行两个排障实录。以下所有命令与输出均为 Ubuntu 22.04（x86_64）实测回显。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（jammy），内核 7.0.0-38-generic，架构 x86_64，root 账号操作
- 目标软件：TextQL 2.0.3（GitHub dinedal/textql；
VERSION文件值 2.0.3） - 三条途径产物对照（均为实测）：
| 途径 | 代码版本 | 产物路径 | 大小 | -sqlfile | -version |
|---|---|---|---|---|---|
| A. apt 发行包 | 2.0.3 release（2015 源码，Debian 2.0.3-4build1，2021-11 打包） | /usr/bin/textql | 3,248,928 B | ❌ 无 | 空行 |
| B. go install | master 伪版本 v0.0.0-20231022225140-e6545d501ca9 | /root/go/bin/textql | 7,690,800 B | ✅ 有 | 空行 |
| C. 源码构建（推荐） | master e6545d5 + ldflags 注入 2.0.3 | /usr/local/bin/textql | 4,408,672 B | ✅ 有 | 2.0.3 |
二、前置条件
途径 A 仅需网络可达 archive.ubuntu.com；途径 B/C 需要 Go 工具链（C 另需 gcc 与 git）。-console 功能另需系统 sqlite3。一次性装齐：
$ apt-get install -y golang-go gcc git sqlite3 curl
版本实测回显：
$ go version
go version go1.18.1 linux/amd64
$ gcc --version | head -1
gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0
$ git --version
git version 2.34.1
$ sqlite3 --version
3.37.2 2022-01-06 13:25:41 872ba256cbf61d9290b571c0e6d82a20c224ca3ad82971edc46b29818d5dalt1
要点：官方 README 仅要求 Go ≥ 1.4，jammy 自带的 1.18.1 满足；依赖 mattn/go-sqlite3 走 CGO，没有 gcc 构建必败（见 9.6）；go.mod 声明 go 1.13。
三、版本选型说明
TextQL 的版本现状（releases Atom 与仓库页，查询日期 2026-11-03）：
- release 序列止于 2.0.3：2.0.0（2015-10-09）→ 2.0.1/2.0.2（2015-12-15）→ 2.0.3（2015-12-17），且 release 页只有 Source code (zip/tar.gz) 资产，无预编译二进制；
- master 最后提交
e6545d5（2023-10-22，PR #141 "read-sql-from-file" 新增-sqlfile参数）； - Ubuntu universe 的
textql包版本2.0.3-4build1，基于 2015 年 release 源码打包（实测无-sqlfile、版本串未注入）。
因此"装 2.0.3"有两条语义：保守（与发行包一致的 2015 代码，途径 A）或功能全（master 代码 + 2.0.3 版本串，途径 C，本文主线推荐）。若你的脚本要用 -sqlfile，必须走 B 或 C。
四、途径 A：apt 发行包安装（最省事，代码最旧）
4.1 方案说明
Ubuntu 22.04 的 universe 源直接提供 textql 包，apt 自动做 GPG 校验，零额外依赖，适合"只想快速有个 textql 用"的场景。
4.2 安装与验证
$ apt-get install -y textql
Fetched 1141 kB in 2s (711 kB/s)
Selecting previously unselected package textql.
(Reading database ... 28021 files and directories currently installed.)
Preparing to unpack .../textql_2.0.3-4build1_amd64.deb ...
Unpacking textql (2.0.3-4build1) ...
Setting up textql (2.0.3-4build1) ...
$ dpkg -l textql | tail -1
ii textql 2.0.3-4build1 amd64 execute SQL against structured text like CSV or TSV
$ ls -la /usr/bin/textql
-rwxr-xr-x 1 root root 3248928 Nov 30 2021 /usr/bin/textql
4.3 该途径的功能边界（实测）
$ /usr/bin/textql -version | cat -A
$
$ /usr/bin/textql 2>&1 | grep -c sqlfile
0
⚠️ 注意：发行包两个硬伤——①
-version打印空行（Debian 构建未注入 VERSION）；② usage 里grep -c sqlfile返回 0，即没有-sqlfile参数（2015 源码）。日常一次性查询够用；要用 SQL 文件驱动必须走途径 C。
4.4 systemd 托管说明
TextQL 是"跑完即退"的一次性 CLI，无常驻进程、无监听端口，不需要 systemd 单元；定时分析场景直接 crontab 调 textql -sql ... 即可。
五、途径 B：go install 安装 master 伪版本
5.1 方案说明
主包在模块的 /textql 子目录，安装命令须写到子包。2.0.3 的 tag（2015 年）早于 go.mod 引入，@latest 解析为 master 伪版本 v0.0.0-20231022225140-e6545d501ca9。模块下载走 Go 模块代理（默认 https://proxy.golang.org,direct），不需要 GitHub 直连，天然绕开第六章的直连问题；本服务器实测 proxy.golang.org 超时、切 goproxy.cn 成功（见 5.2）。
5.2 执行与产物验证（含模块代理降级实录）
$ go install github.com/dinedal/textql/textql@latest
go: github.com/dinedal/textql/textql@latest: module github.com/dinedal/textql/textql: Get "https://proxy.golang.org/github.com/dinedal/textql/textql/@v/list": dial tcp 142.251.34.209:443: i/o timeout
⚠️ 排障实录：本服务器默认 GOPROXY（proxy.golang.org）30 秒超时。换国内模块代理即时成功：
$ GOPROXY=https://goproxy.cn,direct go install github.com/dinedal/textql/textql@latest
# 实测 2.4 秒完成，仅 go-sqlite3 的 C 编译警告，无错误
$ ls -la /root/go/bin/textql
-rwxr-xr-x 1 root root 7690800 Nov 3 05:11 /root/go/bin/textql
$ go version -m /root/go/bin/textql | head -3
/root/go/bin/textql: go1.18.1
path github.com/dinedal/textql/textql
mod github.com/dinedal/textql v0.0.0-20231022225140-e6545d501ca9 h1:Rf5A+wd86aNGFBD9SHmxfcZUcls2GgNUtBcSZ5FxvzM=
$ /root/go/bin/textql -version | cat -A
$
$ /root/go/bin/textql 2>&1 | grep -c sqlfile
1
⚠️ 注意：
go install不执行 Makefile 的 ldflags，产物-version是空行；但代码是 master（grep -c sqlfile返回 1，含-sqlfile）。要版本串可辨就走途径 C。
5.3 纳入 PATH
产物在 $HOME/go/bin，默认不在 PATH：
$ echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
六、途径 C：源码构建（推荐主线：-sqlfile + 2.0.3 版本串）
6.1 拉取源码（含网络降级实录）
$ mkdir -p /work && cd /work
$ timeout 200 git ls-remote https://github.com/dinedal/textql.git
error: RPC failed; curl 16 Error in the HTTP2 framing layer
fatal: expected flush after ref listing
$ echo $?
128
⚠️ 排障实录：本服务器 GitHub 直连不稳定——实测一次 33 秒后报
curl 16 Error in the HTTP2 framing layer（exit 128），另一次挂到 136 秒超时。常规机房直连 GitHub 通常正常，可先直接 clone；若同样失败，改走 HTTP 代理即时成功：
$ git -c http.proxy=http://192.168.1.72:7897 ls-remote https://github.com/dinedal/textql.git | head -3
e6545d501ca9c523110526e7b842d9301451e159 HEAD
48167d14826bbfde4623f245854548538721ae30 refs/heads/feature/v2
e483954a9177f4ecd77376717b03592b25ced7d0 refs/heads/gh-pages
$ git -c http.proxy=http://192.168.1.72:7897 clone https://github.com/dinedal/textql.git textql-src
Cloning into 'textql-src'...
$ cd textql-src && git log -1 --format="%h %ad %s" --date=short
e6545d5 2023-10-22 Merge pull request #141 from naoyafurudono/read-sql-from-file
$ cat VERSION
2.0.3
实测走代理 1.4 秒完成 clone（time 输出 real 0m1.385s）。
6.2 make test 失败实录与绕行
Makefile 的默认目标 textql 会先跑 go test ./...，实测该测试套件有一个断言与实现不符的失败用例：
$ go test ./... 2>&1 | tail -8
--- FAIL: TestCSVInputHasAName (0.00s)
csv_test.go:140: Name() = csv3845608131, want ./csv3845608131
FAIL
FAIL github.com/dinedal/textql/inputs 0.001s
? github.com/dinedal/textql/outputs [no test files]
? github.com/dinedal/textql/sqlparser [no test files]
ok github.com/dinedal/textql/sqlparser/sqltypes (cached)
ok github.com/dinedal/textql/storage (cached)
FAIL
⚠️ 排障实录：
TestCSVInputHasAName断言表名应带./前缀，而实现返回去前缀的基名——停更项目无人修，不影响构建产物（表名基名行为正是我们依赖的）。绕行：用make fast（跳过 test）或直接go build。
6.3 make fast 得到 2.0.3-dev
$ make fast
go build -i -ldflags "-X main.VERSION=`cat VERSION`-dev -s" -o ./build/textql ./textql/main.go
$ ./build/textql -version
2.0.3-dev
-dev 后缀来自 Makefile 硬编码。要正式版本串走下一步。
6.4 正式构建（ldflags 注入 2.0.3）
$ go build -ldflags "-X main.VERSION=2.0.3 -s" -o build/textql ./textql/main.go
$ ./build/textql -version
2.0.3
$ ls -la build/
total 4316
drwxr-xr-x 2 root root 4096 Nov 3 04:35 .
drwxr-xr-x 12 root root 4096 Nov 3 04:35 ..
-rwxr-xr-x 1 root root 4408672 Nov 3 04:35 textql
6.5 安装与验证
$ install -m 755 build/textql /usr/local/bin/textql
$ textql -version
2.0.3
$ ldd /usr/local/bin/textql
linux-vdso.so.1 (0x0000779b1c2f8000)
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x0000779b1c0c4000)
/lib64/ld-linux-x86-64.so.2 (0x0000779b1c2fa000)
$ textql -sql "count(*)" /root/textql-lab/sales.csv
11
ldd 显示仅依赖 glibc，SQLite 已 CGO 静态编入单二进制；冒烟查询正常（sales.csv 未带 -header，表头行也算数据，故 11）。
6.6 三途径并存与 PATH 遮蔽
三条途径的产物路径不同（/usr/bin、$HOME/go/bin、/usr/local/bin），同机并存时 textql 实际执行哪一个由 PATH 顺序决定：
$ which -a textql
/usr/local/bin/textql
/usr/bin/textql
/bin/textql
/usr/local/bin 在 /usr/bin 之前，故默认命中源码构建版。切换版本时记得 hash -r 刷新命令缓存。
七、其他分发渠道说明
官方 README 另列两渠道，均不适用 Ubuntu 22.04：macOS 用 Homebrew（brew install textql）、Arch 用 AUR（textql-git）。本文以服务器二进制安装为主线。
八、方案对比与选择建议
| 维度 | A. apt 发行包 | B. go install | C. 源码构建 |
|---|---|---|---|
| 代码版本 | 2015 release | 2023 master | 2023 master |
-sqlfile | 无 | 有 | 有 |
-version 输出 | 空行 | 空行 | 2.0.3 |
| 联网需求 | archive.ubuntu.com | proxy.golang.org | GitHub（或代理）+ 模块缓存 |
| 额外依赖 | 无 | Go 工具链 | Go + gcc(CGO) + git |
| 产物 | /usr/bin/textql（3.2 MB） | /root/go/bin/textql（7.7 MB） | /usr/local/bin/textql（4.3 MB） |
| 完整性校验 | apt GPG | 模块 h1 哈希 | 无官方 checksum |
| 升级/卸载 | apt remove | 重跑 go install / rm 单文件 | rm 单文件 |
解读：只想要个能用的 textql、不碰 -sqlfile → A（最快、有 GPG）；要新功能且接受版本串为空 → B（免 clone，走模块代理天然规避 GitHub 直连问题）；要"版本可辨 + 新功能 + 可控构建" → C（本文主线）。
九、配置说明
TextQL 没有配置文件：全部行为由 13 个命令行参数决定，不存在 .textql/config.json 或环境变量配置（源码级论证见《TextQL 2.0.3 配置参数详解》第二章）。两个可选外部件：
sqlite3（3.37.2 实测）：仅-console需要；libgo-sqlite3-extension-functions.so：安装后启动时自动加载（stdev/median 等扩展函数），不装则无。
十、常见问题
10.1 apt 装完为什么没有 -sqlfile？
发行包基于 2015 年 release 源码；-sqlfile 是 2023-10 master（PR #141）新增。走途径 B/C。
10.2 -version 打印空行？
VERSION 靠构建时 -ldflags "-X main.VERSION=..." 注入，apt 包与 go install 都未注入。途径 C 按 6.4 构建即可。
10.3 make 报 TestCSVInputHasAName FAIL？
已知测试断言与实现不符（6.2 实录），停更无人修。用 make fast 或直接 go build -ldflags ... 绕行，不影响产物。
10.4 git clone 卡住/报 HTTP2 framing error？
本服务器实测直连 GitHub 33 秒报 curl 16 Error in the HTTP2 framing layer、另次 136 秒超时；git -c http.proxy=http://192.168.1.72:7897 clone ... 秒级成功（6.1 实录）。长期方案：git config --global http.proxy http://192.168.1.72:7897。
10.5 go install 命令应该写到哪一层？
主包在模块子目录，命令必须写到 github.com/dinedal/textql/textql@latest（末尾 /textql）；模块根路径下没有可执行包。
10.6 构建报 cgo: C compiler "gcc" not found？
mattn/go-sqlite3 走 CGO。apt-get install -y gcc 后重试。
10.7 -console 报 unable to locate sqlite3？
-console 会 fork 系统 sqlite3。apt-get install -y sqlite3 解决；纯查询场景不需要。
10.8 装完哪个版本生效？
which -a textql 看遮蔽顺序（6.6 实测），换版本后 hash -r。
10.9 go install 报 proxy.golang.org i/o timeout？
本服务器实测默认 GOPROXY 30 秒超时（dial tcp 142.251.34.209:443: i/o timeout）。GOPROXY=https://goproxy.cn,direct go install ... 实测 2.4 秒成功（5.2 实录）；长期生效用 go env -w GOPROXY=https://goproxy.cn,direct。
十一、卸载与清理
三条途径产物逐一移除并验证（实测回显）：
$ apt-get remove -y textql
Removing textql (2.0.3-4build1) ...
$ rm -f /usr/local/bin/textql /root/go/bin/textql
$ hash -r
$ which -a textql
(textql gone)
$ textql -version
bash: line 5: textql: command not found
$ echo $?
127
源码目录与测试数据按需清理：rm -rf /work/textql-src /root/textql-lab。
十二、参考链接
- 官方仓库：https://github.com/dinedal/textql
- 发布页（2.0.3，仅 Source code）：https://github.com/dinedal/textql/releases/tag/2.0.3
- Ubuntu 包页：https://packages.ubuntu.com/jammy/textql
- 主包源码位置：https://github.com/dinedal/textql/tree/master/textql
- 扩展函数库：https://github.com/dinedal/go-sqlite3-extension-functions
- 选型背景：《TextQL 介绍与选型指南》