OctoSQL 0.13.0 安装部署指南
OctoSQL 0.13.0 在 Ubuntu 22.04 查询服务器 + PostgreSQL 16 数据库服务器上的完整部署：GitHub 直连超时降级代理下载、sha256 校验、单二进制安装、postgres 插件安装与落盘布局、octosql.yml 数据源注册（schema 必填）、三源 JOIN 冒烟测试与三条排障实录。
OctoSQL 0.13.0 安装部署指南
本文在两台真实服务器上完整部署 OctoSQL v0.13.0：查询服务器 app01（Ubuntu 22.04，root 登录）与数据库服务器 db01（PostgreSQL 16，管理员账号 admin/q1w2e3r4，业务库 demo）。OctoSQL 本体是单个 Go 二进制，装完即可查本地文件；要查 db01 上的 PostgreSQL，还需安装 postgres 插件并写好 ~/.octosql/octosql.yml。全流程含下载超时与代理降级的真实排障记录，命令与输出均为实测逐行照抄。
为什么选 v0.13.0：它是官方最新稳定版（2024-05-11 发布），仓库与维护状态的甄别见本专栏《OctoSQL 0.13.0 介绍与选型指南》。
一、前置条件与部署拓扑
| 主机 | 角色 | 系统 | 说明 |
|---|---|---|---|
| app01 | OctoSQL 查询服务器 | Ubuntu 22.04 | 安装 octosql 二进制与插件，数据目录 /opt/datasets |
| db01 | PostgreSQL 数据库服务器 | PostgreSQL 16 | 库 demo、模式 public、表 bonus，账号 admin/q1w2e3r4 |
app01 需要的系统依赖只有 curl（下载）与 ca-certificates；graphviz 仅在用 --explain 渲染查询计划时需要（见第八节）。二进制为纯 Go 静态编译，无其他运行时依赖。
二、下载安装包
2.1 资产清单与校验和
官方 Releases 页（https://github.com/cube2222/octosql/releases/tag/v0.13.0）为每个平台提供 tar.gz 包，octosql_0.13.0_checksums.txt 全文实测如下：
4736b55ed99f6d2504b408612bbcea9a0b9cc2f5853cefc0a8b70b56737010d5 octosql_0.13.0_windows_arm64.tar.gz
49963463c2dc515bedd7e9d77e0e75a394532102ce878caa097250a8260aa815 octosql_0.13.0_linux_amd64.tar.gz
70a3100f093147a3dfe360505bee1eed89c66924410298b5560c62b7e7d51591 octosql_0.13.0_darwin_amd64.tar.gz
8455bc6f9f9164d4469b286bcb58921887e2fe9390e50195fa2f4ea45d85d235 octosql_0.13.0_linux_arm64.tar.gz
994328eb8493562903148861eb09619adfbaa017866b599783847aed677c1fac octosql_0.13.0_darwin_arm64.tar.gz
e87029a1e99a5ac20563d5bf803020a33b5416540d35f535a5be7bcd6cd04785 octosql_0.13.0_windows_amd64.tar.gz
本文用 octosql_0.13.0_linux_amd64.tar.gz（7,132,123 字节）。
2.2 下载：官方源直连超时，降级代理（实录）
在 app01 上首选直连官方 GitHub Releases：
root@app01:~# cd /root
root@app01:~# time curl -fsSL -O https://github.com/cube2222/octosql/releases/download/v0.13.0/octosql_0.13.0_linux_amd64.tar.gz
curl: (28) Failed to connect to github.com port 443 after 135317 ms: Connection timed out
real 2m15.325s
user 0m0.002s
sys 0m0.008s
直连 443 超时（本机房出口到 GitHub 的连接不稳定，此前也出现过 SSL 中途断流）。按降级链切换到本地代理 192.168.1.72:7897，一次成功：
root@app01:~# time curl -fsSL -x http://192.168.1.72:7897 -O https://github.com/cube2222/octosql/releases/download/v0.13.0/octosql_0.13.0_linux_amd64.tar.gz -O https://github.com/cube2222/octosql/releases/download/v0.13.0/octosql_0.13.0_checksums.txt
real 0m1.558s
user 0m0.063s
sys 0m0.016s
root@app01:~# ls -la octosql_0.13.0*
-rw-r--r-- 1 root root 606 Nov 3 03:52 octosql_0.13.0_checksums.txt
-rw-r--r-- 1 root root 7132123 Nov 3 03:52 octosql_0.13.0_linux_amd64.tar.gz
2.3 校验
root@app01:~# sha256sum -c --ignore-missing octosql_0.13.0_checksums.txt
octosql_0.13.0_linux_amd64.tar.gz: OK
三、安装二进制
tar 包内容只有三个文件（实测 tar -tzf）：
LICENSE
README.md
octosql
解压并安装到 /usr/local/bin：
root@app01:~# tar -xzf octosql_0.13.0_linux_amd64.tar.gz
root@app01:~# ls -la octosql
-rwxr-xr-x 1 1001 127 18878464 May 11 2024 octosql
root@app01:~# install -m 755 octosql /usr/local/bin/octosql
root@app01:~# octosql --version
octosql version 0.13.0
安装完成，此刻已可查询任意本地文件（CSV/TSV/JSON Lines/Parquet/Lines）：
root@app01:~# cd /opt/datasets
root@app01:/opt/datasets# octosql "SELECT * FROM employees.csv"
+------+--------------+---------+--------+
| id | name | dept_id | salary |
+------+--------------+---------+--------+
| 1001 | 'Alice Wang' | 1 | 18500 |
| 1002 | 'Bob Chen' | 1 | 16200 |
| 1003 | 'Carol Li' | 2 | 21000 |
| 1004 | 'Dave Zhang' | 2 | 19800 |
| 1005 | 'Eve Liu' | 3 | 15600 |
| 1006 | 'Frank Zhao' | 3 | 17400 |
| 1007 | 'Grace Sun' | 1 | 22300 |
+------+--------------+---------+--------+
四、安装 PostgreSQL 插件
数据库源不在二进制里，必须装插件。插件从各自的 GitHub Release 下载，同样受直连不稳定影响——首次安装即超时（实录）：
root@app01:/opt/datasets# time octosql plugin install postgres
Downloading core/postgres@0.3.0...
Error: couldn't get plugin: Get "https://github.com/cube2222/octosql-plugin-postgres/releases/download/0.3.0/octosql-plugin-postgres_0.3.0_linux_amd64.tar.gz": dial tcp 20.205.243.166:443: i/o timeout
real 0m30.915s
user 0m0.008s
sys 0m0.009s
octosql 的插件下载遵循标准 https_proxy 环境变量，带代理重试 1.9 秒完成：
root@app01:/opt/datasets# time https_proxy=http://192.168.1.72:7897 octosql plugin install postgres
Downloading core/postgres@0.3.0...
real 0m1.862s
user 0m0.068s
sys 0m0.042s
安装后插件落盘在 ~/.octosql/plugins 下，按"仓库 slug/插件名/版本"三层组织（实测 find /root/.octosql/plugins）：
/root/.octosql/plugins/core
/root/.octosql/plugins/core/octosql-plugin-postgres
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/LICENSE
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/README.md
/root/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/octosql-plugin-postgres
插件装没装、装了什么版本，可以用 SQL 直接查（系统表详解见本专栏《OctoSQL 0.13.0 常用 CLI 命令详解》）：
root@app01:/opt/datasets# octosql "SELECT * FROM plugins.installed_plugins" -o batch_table
+---------------+-----------+
| name | repo_slug |
+---------------+-----------+
| 'postgres' | 'core' |
| 'random_data' | 'core' |
+---------------+-----------+
五、数据库服务器 db01 端准备
OctoSQL 只做只读查询，但连接账号要有目标表的 SELECT 权限。db01 上 demo 库的 public.bonus 表用 psql 建立（管理员账号 admin，密码 q1w2e3r4）：
root@db01:~# export PGPASSWORD=q1w2e3r4
root@db01:~# psql -h 127.0.0.1 -U admin -d demo -c "CREATE TABLE public.bonus (emp_id int, quarter text, bonus numeric(10,2));"
CREATE TABLE
root@db01:~# psql -h 127.0.0.1 -U admin -d demo -c "INSERT INTO public.bonus (emp_id, quarter, bonus) VALUES (1001,'2026Q3',3000.00),(1002,'2026Q3',2500.00),(1003,'2026Q3',4200.00),(1004,'2026Q3',3800.00),(1005,'2026Q3',1500.00),(1001,'2026Q4',3500.00),(1003,'2026Q4',4600.00),(1007,'2026Q4',5100.00);"
INSERT 0 8
root@db01:~# psql -h 127.0.0.1 -U admin -d demo -c "SELECT count(*) FROM public.bonus;"
count
-------
8
(1 row)
生产环境建议为 OctoSQL 单独建只读账号并限制来源 IP（pg_hba.conf 加 host 条目），而不是直接用管理员账号。
六、配置数据源 octosql.yml
在 app01 上创建 ~/.octosql/octosql.yml，把 db01 注册为命名数据库 hrdb（配置项逐项说明见《OctoSQL 0.13.0 配置参数详解》）：
databases:
- name: hrdb
type: postgres
config:
host: db01
port: 5432
database: demo
schema: public
user: admin
password: q1w2e3r4
注意 schema: public 这一行不能省：postgres 插件 0.3.0 实测要求 schema 必填，缺了会在查询时报 `schema` configuration setting is required（见第十节实录 3）。
七、冒烟测试
单源连通性——查 db01 的表：
root@app01:/opt/datasets# octosql "SELECT COUNT(*) AS c FROM hrdb.bonus" -o batch_table
+---+
| c |
+---+
| 8 |
+---+
三源联邦 JOIN——app01 上的 CSV 文件 + JSON Lines 文件 + db01 上的 PostgreSQL 表，一条 SQL 出结果：
root@app01:/opt/datasets# octosql "SELECT e.name, d.name AS dept, d.location, b.quarter, b.bonus FROM employees.csv e JOIN \`json.departments.jsonl\` d ON e.dept_id = int(d.id) JOIN hrdb.bonus b ON b.emp_id = e.id ORDER BY e.name, b.quarter"
+--------------+---------------+------------+----------+-------+
| name | dept | location | quarter | bonus |
+--------------+---------------+------------+----------+-------+
| 'Alice Wang' | 'Engineering' | 'Shanghai' | '2026Q3' | 3000 |
| 'Alice Wang' | 'Engineering' | 'Shanghai' | '2026Q4' | 3500 |
| 'Bob Chen' | 'Engineering' | 'Shanghai' | '2026Q3' | 2500 |
| 'Carol Li' | 'Finance' | 'Beijing' | '2026Q3' | 4200 |
| 'Carol Li' | 'Finance' | 'Beijing' | '2026Q4' | 4600 |
| 'Dave Zhang' | 'Finance' | 'Beijing' | '2026Q3' | 3800 |
| 'Eve Liu' | 'Operations' | 'Shenzhen' | '2026Q3' | 1500 |
| 'Grace Sun' | 'Engineering' | 'Shanghai' | '2026Q4' | 5100 |
+--------------+---------------+------------+----------+-------+
部署完成。JOIN 条件里的 int(d.id) 是必需的：JSON 数字解析为 Float，CSV 数字是 Int，不转换会静默查出空表（实测坑，详见选型指南第五节）。
八、可选组件
graphviz（--explain 渲染查询计划）。不装时 --explain 报错：
Error: couldn't render graph: exec: "dot": executable file not found in $PATH
安装后即可用（计划图输出为 PNG，详见 D1）：
root@app01:~# apt-get install -y graphviz
root@app01:~# dot -V
dot - graphviz version 2.43.0 (0)
Shell 补全。octosql 自带补全脚本生成（需系统有 bash-completion，Ubuntu 22.04 最小化安装默认没有，实测直接重定向会报 /etc/bash_completion.d: No such file or directory，先补装）：
root@app01:~# apt-get install -y bash-completion
root@app01:~# octosql completion bash > /etc/bash_completion.d/octosql
root@app01:~# wc -l /etc/bash_completion.d/octosql
288 /etc/bash_completion.d/octosql
root@app01:~# head -2 /etc/bash_completion.d/octosql
# bash completion V2 for octosql -*- shell-script -*-
关闭遥测。octosql 启动会尝试向 telemetry.octosql.dev 上报，该域名已失效，每次运行都会在 ~/.octosql/logs.txt 里留一条 lookup 失败记录。用环境变量关闭：
root@app01:~# OCTOSQL_NO_TELEMETRY=1 octosql "SELECT 1 AS ok"
+----+
| ok |
+----+
| 1 |
+----+
需要长期关闭可把 export OCTOSQL_NO_TELEMETRY=1 写入 /etc/profile.d/octosql.sh 或 ~/.bashrc。
九、升级与卸载
- 升级：OctoSQL 无包管理器渠道，升级即"下载新版本 tar → 校验 → 覆盖
/usr/local/bin/octosql"。插件与主程序版本独立（octosql plugin install <name>@<version>可指定版本），主程序升级后若配置里引用的插件版本不满足要求，会报database 'hrdb' plugin 'core/postgres' used in configuration is not installed with the required version，重装插件即可。 - 卸载：删三处——
rm /usr/local/bin/octosql；rm -rf ~/.octosql（配置、插件、日志、遥测数据全在这里）；rm -f /etc/bash_completion.d/octosql。无服务、无端口、无系统级残留。
十、排障实录
实录 1：GitHub 直连下载超时/断流。
现象：curl: (28) Failed to connect to github.com port 443 after 135317 ms: Connection timed out（主程序），或 dial tcp 20.205.243.166:443: i/o timeout（插件）。
处置：主程序下载用 curl -x http://<代理>:7897；插件安装用 https_proxy=<代理> 环境变量前缀。两者实测均秒级完成。若环境完全无外网，可在有网机器下载后 scp 过去，主程序按第二、三节流程校验安装，插件手动解压到 ~/.octosql/plugins/core/octosql-plugin-postgres/0.3.0/ 并保证可执行位。
实录 2：装好插件前查询报"插件未安装"。
现象：octosql.yml 里写了 postgres 数据库但没装插件，任何查询（包括纯文件查询）启动即报：
Error: database 'hrdb' plugin 'core/postgres' used in configuration is not installed with the required version - run `octosql plugin install` to install all missing plugins
处置：octosql plugin install postgres。注意这个错误发生在配置加载阶段，哪怕你查的只是一个 CSV 文件也会被拦住——octosql.yml 里声明的每个数据库的插件都必须就位。
实录 3：postgres 配置缺 schema 报错。 现象：只按插件 README 写了 host/port/database/user/password 五个参数，查询报：
Error: typecheck error: couldn't create datasource: couldn't get table from plugin: rpc error: code = Unknown desc = couldn't get table: `schema` configuration setting is required
处置：config 下补 schema: public（或目标模式名）。插件 README 的参数表没列这一项，属于文档滞后，以实测报错为准。
十一、小结
OctoSQL 的部署成本几乎为零：一个 19 MB 二进制 + 一个 YAML 配置 + 一个插件。真正要留心的是三件事——GitHub 链路可用性（下载与插件安装都走 GitHub Releases，国内环境备好代理降级）、插件必须先于配置就位、postgres 的 schema 必填。完成本指南后，你的 app01 已具备跨文件与跨数据库的联邦查询能力，进阶用法见《OctoSQL 0.13.0 配置参数详解》与《OctoSQL 0.13.0 常用 CLI 命令详解》。