Ubuntu 22.04 安装 Databag 0.1.18 指南

目标：在 Ubuntu 22.04 真实服务器上从官方源码编译安装 Databag 服务端（0.1.18），含 systemd 托管、TLS 直挂与完整验证。所有命令与回显均来自 2026-10-25 的真实装机实测（Go 1.24.9 / 官方 main 分支源码）。

一、环境信息

操作系统：Ubuntu 22.04 LTS（amd64）
组件版本：Databag 服务端 0.1.18（源码 main 分支，即官方服务端 0.1.18 发布同期代码；服务端版本线见版本选型说明）
编译工具链：Go 1.24.9（go1.24.9.linux-amd64.tar.gz，go.mod 要求 go 1.23.0 + toolchain go1.24.5，apt 仓库的 golang 1.18 不满足）
系统依赖：sqlite3、imagemagick、ffmpeg、build-essential（CGO 编译 go-sqlite3 需要 gcc）
数据目录：/var/lib/databag（SQLite 库 + 账号附件 + 证书）
安装目录：/opt/databag（二进制 bin/、Web 前端 web/、转码脚本 transform/、源码 src/）
监听端口：7000（HTTP；Databag 生产惯例端口，程序默认 443）

二、前置条件

一台可联网的 Ubuntu 22.04 服务器（root 或 sudo 权限）
至少 512MB 内存（编译期建议 1GB+，运行期实测仅需约 23MB）
正式对外使用需准备：指向本机的 DNS 域名 + TLS 证书（Databag 客户端强制要求；本机体验可跳过）

三、版本选型说明

Databag 存在双轨版本号，部署服务端前必须分清（实查 2026-10-25）：

版本线	载体	当前最新	说明
服务端	官方服务端发布（balzack/databag 发布渠道）	0.1.18（2025-10-15）	本文安装对象
客户端 App / Web 前端	GitHub Releases v1.1.x	v1.1.1021	Release 附件只有 `webapp.tar.gz`（预编译前端）

裸机安装 = 「main 分支源码编译服务端」+「GitHub Release 的预编译 webapp.tar.gz 前端」，二者组合正好对应官方服务端 0.1.18 发布的内容。服务端无独立二进制发布件，只能从源码构建，这是 Databag 裸机安装与多数 Go 项目的最大差异。

四、方案 A：在线源码编译安装（推荐）

4.1 方案说明

从 GitHub 拉取源码，本机安装 Go 工具链直接编译，配合官方 Release 的预编译前端，全程约 10 分钟。适合可联网服务器。

4.2 安装系统依赖

apt-get update
apt-get install -y curl wget sqlite3 imagemagick ffmpeg build-essential ca-certificates

实测回显（尾部节选）：

Running hooks in /etc/ca-certificates/update.d...
done.
Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.8+dfsg-1ubuntu0.5) ...

各依赖的作用：sqlite3 用于初始化内置数据库；imagemagick/ffmpeg 是图片与音视频附件转码的运行时依赖（服务端的 -t transform 脚本调用它们）；build-essential 提供 gcc，编译期 CGO 必需。

4.3 安装 Go 工具链

apt 源里的 golang 是 1.18，低于 go.mod 要求的 1.23，必须从官方下载：

wget https://go.dev/dl/go1.24.9.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.24.9.linux-amd64.tar.gz
/usr/local/go/bin/go version

实测回显：

go version go1.24.9 linux/amd64

⚠️ 网络说明：实测时本机直连 go.dev/github.com 超时，经代理 192.168.1.62:7897 下载成功（wget -x http://192.168.1.62:7897 <URL>）。若你的服务器可直连官方源则无需代理；Go 模块下载环节的渠道选择见 4.5 的实测记录。

4.4 下载源码与前端包

mkdir -p /opt/databag
# 源码（main 分支快照，约 47MB，含文档/设计稿）
wget https://codeload.github.com/balzack/databag/tar.gz/refs/heads/main -O databag-main.tar.gz
tar -C /opt/databag -xzf databag-main.tar.gz
mv /opt/databag/databag-main /opt/databag/src

# 预编译 Web 前端（GitHub Release 附件，约 2.6MB）
wget https://github.com/balzack/databag/releases/download/v1.1.1021/webapp.tar.gz
mkdir -p /opt/databag/src/net/web/build
tar -xf webapp.tar.gz -C /opt/databag/src/net/web/build/
ls /opt/databag/src/net/web/build/

实测回显：

asset-manifest.json
favicon.ico
index.html
logo192.png
logo512.png
...

💡 说明：前端是 React 工程（app/client/web），也可以用 Node 22 + yarn 自行 yarn build；官方为低功耗设备（React 工具链跑不动的树莓派 Zero）提供了预编译包，直接解压最省事。

4.5 编译服务端

cd /opt/databag/src/net/server
export PATH=/usr/local/go/bin:$PATH
CGO_ENABLED=1 go build -o databag .

⚠️ 实测排障记录（网络渠道降级）：先按默认官方源 proxy.golang.org 构建，依赖 zip 下载被拒绝连接：

internal/authUtil.go:7:2: golang.org/x/crypto@v0.40.0: Get "https://proxy.golang.org/golang.org/x/crypto/@v/v0.40.0.zip": dial tcp 142.251.45.145:443: connect: connection refused

按「官方源 → 国内源」降级链改用 goproxy.cn 后成功：

export GOPROXY=https://goproxy.cn,direct
CGO_ENABLED=1 go build -o databag .

实测回显（尾部节选）：

go: downloading github.com/mattn/go-sqlite3 v1.14.22
go: downloading github.com/jinzhu/inflection v1.0.0

编译耗时实测约 47 秒（4 核 amd64），产物约 17MB：

ls -la databag

-rwxr-xr-x 1 root root 17691544 Oct 25 04:36 databag

⚠️ 注意：CGO_ENABLED=1 不可省略——SQLite 驱动 mattn/go-sqlite3 是 CGO 绑定，禁用 CGO 会编译失败。

4.6 部署目录与数据库初始化

mkdir -p /opt/databag/bin /opt/databag/web /var/lib/databag
cp /opt/databag/src/net/server/databag /opt/databag/bin/
cp -r /opt/databag/src/net/web/build/* /opt/databag/web/
cp -r /opt/databag/src/net/transform /opt/databag/transform

初始化内置数据库（configs 表是服务端全部配置的载体，必须手工建表，否则启动后无法写入配置）：

sqlite3 /var/lib/databag/databag.db "VACUUM;"
sqlite3 /var/lib/databag/databag.db "CREATE TABLE IF NOT EXISTS 'configs' ('id' integer NOT NULL UNIQUE,'config_id' text NOT NULL,'str_value' text,'num_value' integer,'bool_value' numeric,'bin_value' blob,PRIMARY KEY ('id'));"
sqlite3 /var/lib/databag/databag.db "CREATE UNIQUE INDEX IF NOT EXISTS 'idx_configs_config_id' ON 'configs'('config_id');"

预置管理员口令（演示口令 q1w2e3r4，生产请替换；等效于官方发布入口脚本 ADMIN 环境变量的行为）：

sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, str_value) values ('token', 'q1w2e3r4');"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, bool_value) values ('configured', true);"

💡 说明：不预置也可以——首次用浏览器访问时会进入「初始设置管理员口令」流程；预置的价值在于自动化部署与找回口令（改口令就是改这条记录，见常见问题）。

4.7 systemd 托管

新建 /etc/systemd/system/databag.service：

[Unit]
Description=Databag federated messenger server
After=network.target

[Service]
Type=simple
ExecStart=/opt/databag/bin/databag -p 7000 -s /var/lib/databag -w /opt/databag/web -t /opt/databag/transform
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启动并验证：

systemctl daemon-reload
systemctl enable databag
systemctl start databag
systemctl status databag --no-pager

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/databag.service → /etc/systemd/system/databag.service.
● databag.service - Databag federated messenger server
     Loaded: loaded (/etc/systemd/system/databag.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 04:37:01 UTC; 2s ago
   Main PID: 8210 (databag)
      Tasks: 10 (limit: 3612)
     Memory: 22.6M
        CPU: 81ms

注意 Memory: 22.6M——印证了官方「树莓派 Zero 可运行」的轻量宣称。

4.8 验证安装

# Web 客户端首页
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:7000/

HTTP 200

# 管理员登录换取会话令牌
curl -s -X PUT "http://127.0.0.1:7000/admin/access?token=q1w2e3r4"

"c802fdfe9aa037d4151149af487c3e65"

# 用会话令牌读取节点配置（确认管理面可用）
curl -s "http://127.0.0.1:7000/admin/config?token=c802fdfe9aa037d4151149af487c3e65"

{"domain":"","enableImage":true,"enableAudio":true,"enableVideo":true,"enableBinary":true,"enableIce":false,"iceService":"","iceUrl":"","iceUsername":"","icePassword":"","keyType":"RSA2048","accountStorage":0,"transformSupported":true,"allowUnsealed":true,"pushSupported":true}

浏览器访问 http://<服务器IP>:7000，点右上角齿轮，输入管理员口令 q1w2e3r4 即可进入管理台创建账号。

五、方案 B：离线介质安装（断网服务器）

5.1 方案说明

目标机完全断网时，在同架构的联网机器上备好 4 样介质，拷贝到目标机执行。编译仍在目标机完成（保证 CGO 链接的库与本机一致），只把「下载」环节搬到联网机。

5.2 联网机准备介质

mkdir databag-offline && cd databag-offline
wget https://go.dev/dl/go1.24.9.linux-amd64.tar.gz
wget https://codeload.github.com/balzack/databag/tar.gz/refs/heads/main -O databag-main.tar.gz
wget https://github.com/balzack/databag/releases/download/v1.1.1021/webapp.tar.gz

关键一步——把 Go 模块依赖缓存一并打包（否则目标机 go build 仍要联网）：

tar -xzf databag-main.tar.gz
cd databag-main/net/server
export PATH=/usr/local/go/bin:$PATH GOPROXY=https://goproxy.cn,direct
go mod download
tar -czf ../../../databag-offline/gomodcache.tar.gz -C $(go env GOMODCACHE) .
cd ../../..
tar -czf databag-offline.tar.gz databag-offline/

5.3 目标机安装

tar -xzf databag-offline.tar.gz && cd databag-offline
tar -C /usr/local -xzf go1.24.9.linux-amd64.tar.gz
mkdir -p /opt/databag && tar -C /opt/databag -xzf databag-main.tar.gz && mv /opt/databag/databag-main /opt/databag/src
mkdir -p /opt/databag/src/net/web/build && tar -xf webapp.tar.gz -C /opt/databag/src/net/web/build/
mkdir -p /root/go && tar -xzf gomodcache.tar.gz -C /root/go/pkg/mod --strip-components=0 2>/dev/null || { mkdir -p /root/go/pkg/mod && tar -xzf gomodcache.tar.gz -C /root/go/pkg/mod; }
cd /opt/databag/src/net/server
export PATH=/usr/local/go/bin:$PATH GOFLAGS=-mod=mod GOPROXY=off
CGO_ENABLED=1 go build -o databag .

GOPROXY=off 强制只用本地缓存，离线构建成功即说明介质完整；之后的数据库初始化、systemd 托管与验证步骤与方案 A 的 4.6–4.8 完全相同。

六、方案对比与选择建议

维度	方案 A 在线编译	方案 B 离线介质
网络要求	目标机可联网	目标机断网，另需联网机
安装耗时	约 10 分钟	目标机约 5 分钟
依赖来源	go.dev + GitHub + GOPROXY	离线 tar 包
适用场景	公网 VPS / 家庭服务器	内网隔离环境

建议：能联网一律走方案 A；只有目标机物理断网才用方案 B。两者产物与后续运维完全一致。

七、配置说明

服务端全部运行参数（实测来自 main.go 与官方发布入口脚本）：

参数	形态	默认值	说明
`-p`	命令行旗标	443	监听端口，本文用 7000
`-s`	命令行旗标	/var/lib/databag	数据目录（SQLite + 附件）
`-w`	命令行旗标	/opt/databag/	Web 前端静态目录
`-t`	命令行旗标	（空）	媒体转码脚本目录，置空则转码能力关闭
`-c` / `-k`	命令行旗标	（空）	TLS 证书/私钥，给了即以 HTTPS 运行
`ADMIN`	环境变量（仅官方发布入口脚本消费）	（空）	预置管理员口令，裸机等价做法见 4.6

TLS 直挂实测（适合无反向代理的场景）：

openssl req -x509 -newkey rsa:2048 -keyout /var/lib/databag/key.pem -out /var/lib/databag/cert.pem -days 365 -nodes -subj "/CN=databag.example.com"
/opt/databag/bin/databag -p 7443 -s /var/lib/databag -w /opt/databag/web -t /opt/databag/transform -c /var/lib/databag/cert.pem -k /var/lib/databag/key.pem

启动日志确认进入 TLS 模式，HTTPS 访问返回 200：

2026/10/25 04:37:29 using args: -s /var/lib/databag -w /opt/databag/web -p 7443 -c /var/lib/databag/cert.pem -k /var/lib/databag/key.pem -t /opt/databag/transform

HTTPS: 200

业务级配置（域名、存储配额、媒体开关、TURN 中继、MFA 等）全部落库在 SQLite configs 表，运行时通过管理台或 PUT /admin/config 修改，逐参数说明见《Databag 0.1.18 配置参数详解》。

八、常见问题

Q1：go build 报 dial tcp ... proxy.golang.org ... connection refused？ 官方 GOPROXY 在你的网络不可达。按降级链处理：先确认是否临时故障，不行则 export GOPROXY=https://goproxy.cn,direct 重试（本文实测可用），仍不行再配 HTTPS_PROXY 走代理。

Q2：忘记管理员口令怎么办？ 口令以明文形态存于 /var/lib/databag/databag.db 的 configs 表（config_id='token'）。重置：

systemctl stop databag
sqlite3 /var/lib/databag/databag.db "delete from configs where config_id='token'; delete from configs where config_id='configured';"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, str_value) values ('token', 'q1w2e3r4');"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, bool_value) values ('configured', true);"
systemctl start databag

Q3：启动报数据库相关错误？ 多为跳过 4.6 的建表步骤。Databag 的 configs 表不是程序自建的（GORM 自动迁移只覆盖业务表），必须按 4.6 手工初始化。

Q4：能不能不用域名和证书？ 本机浏览器体验可以（http://IP:7000）；但移动端 App 与联邦互联都要求「DNS 域名 + 有效证书」，正式使用必须配置（反向代理 TLS 或 -c/-k 直挂均可）。

九、卸载与清理

systemctl stop databag
systemctl disable databag
rm /etc/systemd/system/databag.service
systemctl daemon-reload
rm -rf /opt/databag /var/lib/databag
# 按需移除 Go 工具链
rm -rf /usr/local/go

十、参考链接

GitHub 仓库：https://github.com/balzack/databag
官方裸机安装参考（树莓派 Zero 版）：https://github.com/balzack/databag/blob/main/doc/pizero.md
Go 官方下载：https://go.dev/dl/
Web 前端预编译包：https://github.com/balzack/databag/releases/download/v1.1.1021/webapp.tar.gz