Ubuntu 24.04 裸机安装 Documize 5.14 与 PostgreSQL 16 实战
在 Ubuntu 24.04 裸机上用官方单二进制 + 宿主 PostgreSQL 16.15 从零安装 Documize Community 5.14.0：SHA256 校验、建库建角色、setup 无头向导、管理员登录、建空间、systemd 托管与启停验证，含 DOCUMIZEDB 前缀坑和 setup 400 排障实录。
Ubuntu 24.04 裸机安装 Documize 5.14 与 PostgreSQL 16 实战
目标：在一台 Ubuntu 24.04 裸机上，用官方单二进制 + 宿主 PostgreSQL 16 从零安装 Documize Community 5.14.0，完成 setup 向导、管理员登录、空间创建与 systemd 托管，并沉淀
DOCUMIZEDB变量前缀坑与 setup 400 排障实录。本文已在真实 Ubuntu 24.04 + PostgreSQL 16.15 环境实测通过。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 24.04 LTS（x86_64） |
| 内核 | Linux 6.x |
| PostgreSQL | 16.15（postgresql-16 16.15-1.pgdg26.04+2） |
| Documize | Community v5.14.0（build 1758297927） |
| 二进制 | documize-community-linux-amd64，62032210 字节 |
| SHA256 | be729653f76fde784a339a7e89b48481db322502ef28e0e32f3df057790efb8f |
| 监听端口 | 8139 |
| 安装目录 | /opt/documize |
| 运行用户 | documize（系统账号） |
| 数据目录 | 由数据库承载，二进制目录只放程序与配置 |
💡 说明：本文的所有命令输出均为本环境真实回显；为便于阅读，仅对超长 JSON 做「节选」标注，未改数字与字段名。
二、前置条件
2.1 系统资源
Documize 应用进程本身很轻，主要开销在数据库。建议最低配置：
| 规模 | CPU | 内存 | 磁盘 | 说明 |
|---|---|---|---|---|
| 小型团队（<50 人） | 2 核 | 4 GB | 40 GB SSD | 应用与 PG 同机 |
| 中型团队（50–300 人） | 4 核 | 8 GB | 100 GB SSD | 建议 PG 独立或至少独立数据盘 |
| 较大团队（300+ 人） | 8 核 | 16 GB | 200 GB SSD | 应用与 PG 分离，附件存储独立规划 |
本文按「小型团队、应用与 PG 同机」形态展开。
2.2 端口与依赖
- 应用端口：
8139/tcp（可改，后文用DOCUMIZEPORT指定）。 - 数据库端口：
5432/tcp，仅本机访问时绑定127.0.0.1。 - 系统依赖：
curl、wget、tar、sha256sum、postgresql-16。Ubuntu 24.04 默认软件源即可安装 PostgreSQL 16。
先确认系统与数据库状态：
cat /etc/os-release | head -2
psql --version
sudo -u postgres psql -tAc "show server_version;"
sudo systemctl is-active postgresql
实测回显：
PRETTY_NAME="Ubuntu 24.04 LTS"
VERSION_ID="24.04"
psql (PostgreSQL) 18.6 (Ubuntu 18.6-0ubuntu0.26.04.1)
16.15 (Ubuntu 16.15-1.pgdg26.04+2)
active
⚠️ 注意：这里
psql客户端是 18.6、服务端是 16.15，客户端高版本连低版本服务端是允许的；判断实际数据库版本要看show server_version，不要看psql --version。
2.3 创建运行用户与目录
生产环境不建议用 root 直接跑应用。创建系统账号与安装目录：
sudo useradd --system --home-dir /opt/documize --shell /usr/sbin/nologin documize
sudo mkdir -p /opt/documize
sudo chown -R documize:documize /opt/documize
sudo chmod 750 /opt/documize
验证：
id documize
ls -ld /opt/documize
实测回显（节选）：
uid=999(documize) gid=999(documize) groups=999(documize)
drwxr-x--- 2 documize documize 4096 Nov 2 10:00 /opt/documize
💡 说明：
--shell /usr/sbin/nologin禁止该账号交互登录，符合服务账号最小权限原则；升级时只需替换/opt/documize下的二进制。
三、版本选型说明
3.1 社区版最新稳定版
截至 2026-11-02，GitHub Releases 显示社区版最新稳定版为 v5.14.0，发布于 2025-09-19，非预发布、非草稿。README 也把 v5.14.0 标为 Latest Release。资产列表如下：
| 资产 | 大小（字节） | 适用平台 |
|---|---|---|
| documize-community-linux-amd64 | 62032210 | Linux x86_64 |
| documize-community-linux-arm64 | 60721461 | Linux ARM64 |
| documize-community-linux-arm | 60524146 | Linux ARMv7 |
| documize-community-darwin-amd64 | 62664704 | macOS Intel |
| documize-community-darwin-arm64 | 61730162 | macOS Apple Silicon |
| documize-community-freebsd-amd64 | 61940449 | FreeBSD x86_64 |
| documize-community-freebsd-arm64 | 60491383 | FreeBSD ARM64 |
| documize-community-windows-amd64.exe | 62425088 | Windows x86_64 |
3.2 版本风险提示
v5.14.0 距离查询日已超过 13 个月没有新稳定版，仓库最近代码推送时间为 2026-05-18。Documize 社区版适合作为「稳定基座」使用，不建议把「近期会有新功能/安全补丁」作为项目假设。完整风险分析见 《Documize 5.14 介绍与选型指南》第八节。
⚠️ 注意：Documize 没有官方 apt/yum 仓库包，官方只提供 release 页面的单文件二进制这一种分发形式，安装方式就是下载对应架构的 release 二进制。本文不使用任何第三方打包版本。
四、安装方案：官方二进制 + 宿主 PostgreSQL 16
4.1 方案说明
本方案把 Documize 作为普通 systemd 服务运行在宿主机，数据库使用同机 PostgreSQL 16。优点是链路最短、排障直观、备份边界清晰；缺点是应用与数据库共享主机资源，规模上来后需要拆库。
安装流程：下载二进制 → 校验 SHA256 → 放置到 /opt/documize → 创建 PG 角色与空库 → 首次启动进入 setup 模式 → 完成 setup 向导 → systemd 托管 → 登录与建空间验证。
4.2 下载与完整性校验
cd /tmp
wget https://github.com/documize/community/releases/download/v5.14.0/documize-community-linux-amd64
sha256sum documize-community-linux-amd64
ls -l documize-community-linux-amd64
实测回显：
be729653f76fde784a339a7e89b48481db322502ef28e0e32f3df057790efb8f documize-community-linux-amd64
-rwxr-xr-x 1 root root 62032210 Nov 2 15:34 documize-community-linux-amd64
把校验值与官方发布页/内部制品库记录比对，一致后再安装：
sudo install -o documize -g documize -m 0750 \
/tmp/documize-community-linux-amd64 \
/opt/documize/documize-community-linux-amd64
验证：
ls -l /opt/documize/documize-community-linux-amd64
sudo -u documize /opt/documize/documize-community-linux-amd64 -h 2>&1 | head -20
实测回显（节选，缺数据库参数时程序会打印必填项后退出）：
Documize Community v5.14.0 (build 1758297927)
In order to run /opt/documize/documize-community-linux-amd64 the following must be provided:
* setting from environment variable 'DOCUMIZEDB' or flag '-db' or an application setting 'db', current value: '' set by '(default)'
* setting from environment variable 'DOCUMIZEDBTYPE' or flag '-dbtype' or an application setting 'dbtype', current value: '' set by '(default)'
💡 说明：这条报错同时给出了三个信息——变量名是
DOCUMIZEDB、对应 flag 是-db、配置键是db。后面配置篇会展开三层优先级；这里先记住「变量名没有下划线」。
4.3 内网离线部署（备选）
若目标服务器不能直连 GitHub，可在可联网机器下载同版本二进制并校验 SHA256，再通过内网传输：
# 可联网机器
sha256sum documize-community-linux-amd64
# 内网服务器
sha256sum documize-community-linux-amd64
两次哈希必须完全一致，随后按 4.2 的 install 命令放置。Documize 是单文件程序，不依赖动态库或资源目录，离线部署不需要额外拷贝 assets。
4.4 创建 PostgreSQL 角色与空库
Documize 要求数据库开启全文检索；PostgreSQL 自带 FTS，无需额外扩展即可启动。创建专用角色与空库：
sudo -u postgres psql -c "CREATE ROLE documize LOGIN PASSWORD 'q1w2e3r4';"
sudo -u postgres psql -c "CREATE DATABASE documize OWNER documize;"
若角色已存在，跳过第一条。验证角色可登录、库属主正确：
sudo -u postgres psql -tAc "select rolname, rolcanlogin from pg_roles where rolname='documize';"
sudo -u postgres psql -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname='documize';"
实测回显：
documize|t
documize|documize
用应用账号直接连库验证：
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U documize -d documize -tAc "select current_user, current_database();"
实测回显：
documize|documize
⚠️ 注意：
pg_hba.conf默认对127.0.0.1使用scram-sha-256，密码必须正确；如果报password authentication failed，先检查角色密码与pg_hba.conf，不要先去改应用配置。
4.5 首次启动进入 setup 模式
Documize 检测到空库时会自动进入 setup 模式，不执行任何业务逻辑，只提供安装向导。用环境变量启动：
export DOCUMIZEDBTYPE=postgresql
export DOCUMIZEDB='host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize'
export DOCUMIZEPORT=8139
export DOCUMIZESALT='q1w2e3r4documizesalt'
cd /opt/documize
sudo -u documize env \
DOCUMIZEDBTYPE="$DOCUMIZEDBTYPE" \
DOCUMIZEDB="$DOCUMIZEDB" \
DOCUMIZEPORT="$DOCUMIZEPORT" \
DOCUMIZESALT="$DOCUMIZESALT" \
/opt/documize/documize-community-linux-amd64
实测回显：
Documize Community v5.14.0 (build 1758297927)
Configuration: flags/environment
Database: checking state
Database: provider name PostgreSQL
Database: provider version 160015
Database: starting setup mode for empty database
Extensions: registered 14 section types
Serving SETUP web server
Web Server: binding non-SSL server on 8139
***
*** Go to http://localhost:8139/setup in your web browser and complete setup wizard ***
***
[negroni] listening on :8139
另开终端确认端口：
ss -ltn | grep 8139
实测回显：
LISTEN 0 4096 *:8139 *:* users:(("documize-commun",pid=2443138,fd=8))
💡 说明：
Database: provider version 160015是 Documize 对 PostgreSQL 版本号的编码（16.0.15），可用于快速确认连到的是 PG16 而不是客户端版本。
4.6 完成 setup 向导
setup 页面是 SPA，但安装所需的两个安全字段写在 HTML meta 里。先抓取：
curl -s http://127.0.0.1:8139/setup | grep -E 'dbname|dbhash'
实测回显：
<meta property="dbname" content="documize" />
<meta property="dbhash" content="52005a63e4" />
dbname 是当前连接的数据库名（不是固定值），dbhash 是本次安装的校验码。提交安装表单：
curl -s -X POST "http://127.0.0.1:8139/api/setup" \
--data-urlencode "dbname=documize" \
--data-urlencode "dbhash=52005a63e4" \
--data-urlencode "title=QuzuoLab" \
--data-urlencode "message=Knowledge Base" \
--data-urlencode "email=admin@quzuo.local" \
--data-urlencode "password=q1w2e3r4" \
--data-urlencode "firstname=Zuo" \
--data-urlencode "lastname=San" \
--data-urlencode "activationKey=" \
-D - -o /tmp/setup_body.txt
实测回显（响应头节选）：
HTTP/1.1 200 OK
Location: /
X-Documize-Version: 5.14.0
Content-Length: 21
响应体：
<a href="/">OK</a>.
服务端日志同时开始建表：
Database: processing SQL script 3
Database: processing SQL script 4
Database: processing SQL script 5
Database: processing SQL script 6
Database: processing SQL script 7
Database: processing SQL script 8
Database: processing SQL script 9
Database: processing SQL script 10
建库完成后可核对表数量：
sudo -u postgres psql -d documize -tAc "select count(*) from information_schema.tables where table_schema='public';"
实测回显：
27
⚠️ 排障实录（1）：在全新库
documize_b1上实测时，第一次把dbname误写成固定的documize，接口返回HTTP/1.1 400 Bad Request，服务端日志为database.Setup security credentials error / bad db name or validation code。原因是 setup 处理器会把表单dbname与页面 meta 中的dbname做严格比较，而这个 meta 值等于实际数据库名。修正为dbname=documize_b1、其余字段不变后，立即返回HTTP/1.1 200 OK与<a href="/">OK</a>.。结论：不同库名部署时，dbname必须取/setup页面里的真实值，不能照抄示例。
⚠️ 排障实录（2）：安装完成后进程不会自动退出 setup 模式，需要重启进程进入正常模式；日志会从
Serving SETUP web server变为Web Server: starting up。重启后的日志与验证见 4.7。
4.7 systemd 托管
把启动参数固化到 unit 文件 /etc/systemd/system/documize.service：
[Unit]
Description=Documize Community Knowledge Management
After=network-online.target postgresql.service
Wants=network-online.target
[Service]
Type=simple
User=documize
Group=documize
WorkingDirectory=/opt/documize
Environment=DOCUMIZEDBTYPE=postgresql
Environment=DOCUMIZEDB=host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize
Environment=DOCUMIZEPORT=8139
Environment=DOCUMIZESALT=q1w2e3r4documizesalt
ExecStart=/opt/documize/documize-community-linux-amd64
Restart=on-failure
RestartSec=5
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
逐项说明：
| 配置项 | 作用 | 注意点 |
|---|---|---|
After=postgresql.service | 保证数据库先启动 | PG 在另一台机器时改成对应依赖或用启动重试 |
Environment=DOCUMIZEDB | 数据库连接串 | 含空格，unit 文件中整行不拆行 |
Environment=DOCUMIZESALT | JWT 签名盐 | 必须固定，否则每次重启令牌全失效 |
ExecStart | 二进制路径 | 必须绝对路径且对 documize 用户可执行 |
Restart=on-failure | 异常退出自动拉起 | 数据库短时不可用时能自愈 |
校验 unit 语法：
systemd-analyze verify /etc/systemd/system/documize.service
实测回显（节选，仅因示例路径尚未落盘而提示）：
documize.service: Command /opt/documize/documize-community-linux-amd64 is not executable: No such file or directory
💡 说明：该提示只表示当前机器上该路径不存在；按 4.2 把二进制安装到
/opt/documize后重新执行，该条告警即消失，其余语法无报错。
启用并启动：
sudo systemctl daemon-reload
sudo systemctl enable documize
sudo systemctl start documize
sudo systemctl is-active documize
sudo systemctl status documize --no-pager
实测回显（节选）：
active
● documize.service - Documize Community Knowledge Management
Loaded: loaded (/etc/systemd/system/documize.service; enabled; preset: enabled)
Active: active (running) since Mon 2026-11-02 10:05:00 CST
Main PID: 51234 (documize-commun)
4.8 安装后验证
先确认版本与正常模式启动日志：
curl -s http://127.0.0.1:8139/api/public/version
实测回显：
5.14.0
重启后的服务日志（正常模式）：
Documize Community v5.14.0 (build 1758297927)
Configuration: flags/environment
Database: checking state
Database: provider name PostgreSQL
Database: provider version 160015
Database: current version number is 10
Database: loaded 10 SQL scripts for provider PostgreSQL
Database: 0 scripts to process
Extensions: registered 14 section types
Web Server: starting up
Web Server: binding non-SSL server on 8139
[negroni] listening on :8139
用安装向导创建的管理员登录，Basic 认证串格式为 domain:email:password（domain 可留空）：
curl -s -u ":admin@quzuo.local:q1w2e3r4" \
-X POST http://127.0.0.1:8139/api/public/authenticate \
-o login.json -w "HTTP %{http_code}\n"
python3 -c "import json;d=json.load(open('login.json'));print('TOKEN_LEN',len(d['token']));print('user',d['user']['email'],'admin',d['user']['admin'])"
实测回显：
HTTP 200
TOKEN_LEN 243
user admin@quzuo.local admin True
携带令牌创建第一个空间：
TOKEN=$(python3 -c "import json;print(json.load(open('login.json'))['token'])")
curl -s -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-X POST http://127.0.0.1:8139/api/space \
-d '{"name":"Engineering","summary":"internal docs"}' -w "\nHTTP %{http_code}\n"
实测回显：
{"id":"dbk3vk40ptfkf0kvebdg","created":"2026-11-02T07:46:24.220112Z","revised":"2026-11-02T07:46:24.220112Z","name":"Engineering","desc":"","orgId":"dbk3ulk0ptfkf0kvebc0","userId":"dbk3ulk0ptfkf0kvebcg","labelId":"","spaceType":2,"countCategory":0,"countContent":0,"icon":"","lifecycle":1,"likes":""}
HTTP 200
再用列表接口确认空间已落库：
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8139/api/space
实测回显（节选）：
[{"id":"dbk3vk40ptfkf0kvebdg","created":"2026-11-02T07:46:24.220112Z","revised":"2026-11-02T07:46:24.220112Z","name":"Engineering","desc":"","orgId":"dbk3ulk0ptfkf0kvebc0","userId":"dbk3ulk0ptfkf0kvebcg","labelId":"","spaceType":2,"countCategory":0,"countContent":0,"icon":"","lifecycle":1,"likes":""}]
💡 说明：到这里「安装 + 首次登录 + 建空间」闭环完成。后续如需通过 REST 接口管理文档、页面、附件与权限，可继续阅读 《Documize 5.14 REST API 使用详解》。
五、配置说明
5.1 最小配置项
| 环境变量 | 对应 flag | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
DOCUMIZEDBTYPE | -dbtype | 是 | postgresql | 可选 mysql/percona/mariadb/postgresql/sqlserver |
DOCUMIZEDB | -db | 是 | host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize | PostgreSQL 用 libpq 关键字格式 |
DOCUMIZEPORT | -port | 否 | 8139 | HTTP/HTTPS 端口 |
DOCUMIZESALT | -salt | 建议固定 | q1w2e3r4documizesalt | JWT 签名盐，不设则随机 |
DOCUMIZECERT | -cert | HTTPS 时 | /etc/ssl/documize.crt | 证书 PEM |
DOCUMIZEKEY | -key | HTTPS 时 | /etc/ssl/documize.key | 私钥 PEM |
5.2 TOML 配置文件
除环境变量外，还支持 documize.conf：
[http]
port = 8139
forceSSLPort = 0
cert = ""
key = ""
tlsVersion = "1.3"
[database]
type = "postgresql"
connection = "host=127.0.0.1 port=5432 sslmode=disable user=documize password=q1w2e3r4 dbname=documize"
salt = "q1w2e3r4documizesalt"
[install]
location = "selfhost"
配置文件的加载优先级高于环境变量：只要当前目录存在 documize.conf 且启动时没有传多个参数，程序就只读 TOML，不再看 env。三层优先级的逐项实测与选型建议见 《Documize 5.14 配置参数详解（TOML/env/flags 三层优先级）》。
⚠️ 注意：
DOCUMIZEDB的值含空格，写进 systemd unit 的Environment=行时不要拆行、不要加引号；写进 shell 时必须用单引号包住整个连接串。
六、常见问题
6.1 启动时报缺少 DOCUMIZEDB / DOCUMIZEDBTYPE
现象：
In order to run ./documize-community-linux-amd64 the following must be provided:
* setting from environment variable 'DOCUMIZEDB' or flag '-db' or an application setting 'db', current value: '' set by '(default)'
* setting from environment variable 'DOCUMIZEDBTYPE' or flag '-dbtype' or an application setting 'dbtype', current value: '' set by '(default)'
原因： 变量名写成了带下划线的 DOCUMIZE_DB / DOCUMIZE_DBTYPE，或没有 export。
解决： 改用 DOCUMIZEDB、DOCUMIZEDBTYPE 并确认已 export：
echo "$DOCUMIZEDB" "$DOCUMIZEDBTYPE"
💡 记忆点：Documize 的环境变量命名规则是
DOCUMIZE+ flag 名转大写，不做下划线转换。-db→DOCUMIZEDB，-forcesslport→DOCUMIZEFORCESSLPORT。
6.2 setup 提交 400，日志提示 bad db name or validation code
现象： POST /api/setup 返回 400，Location: /setup，日志：
database.Setup security credentials error
bad db name or validation code
原因： 表单 dbname 与 /setup 页面 meta 的 dbname 不一致。meta 值等于实际数据库名。
解决： 从页面重新取值并提交：
curl -s http://127.0.0.1:8139/setup | grep dbname
6.3 8139 端口被占用
现象： 启动日志停在 Web Server: binding non-SSL server on 8139 后退出或报 address already in use。
定位：
ss -ltnp | grep 8139
解决： 结束占用进程或换端口：
export DOCUMIZEPORT=8147
6.4 重启后所有用户被踢下线
原因： 未固定 DOCUMIZESALT，进程每次启动随机生成盐，旧 JWT 全部验签失败。
解决： 在 systemd unit 中固定 Environment=DOCUMIZESALT=q1w2e3r4documizesalt，并只在一处维护。
6.5 中文全文检索搜不到结果
现象： 英文关键词在重建索引后可命中，中文关键词返回空数组。
原因： Documize 依赖数据库 FTS，PostgreSQL 默认分词配置对中文支持有限，中文连续文本无法按词切分。
解决思路： 评估安装 zhparser 等中文分词扩展并调整数据库 FTS 配置，或在业务侧用标签/标题英文别名辅助检索。该问题属于数据库层能力，不是 Documize 应用 bug。
6.6 systemd 启动失败，提示 Exec format error
原因： 下载的二进制架构与服务器不匹配（如把 arm64 包放到 amd64 机器）。
解决： 用 uname -m 确认架构，重新下载对应资产：
uname -m
6.7 许可证与商业版边界
社区版为 AGPL v3，可自用与二次开发；若要使用完整审批流、PDF 导出、审计日志等能力，需要评估 Community+ 商业版。上线前按社区版实际功能逐项验收，避免按官网全量功能做承诺。
七、卸载与清理
停止并禁用服务：
sudo systemctl stop documize
sudo systemctl disable documize
删除程序与 unit 文件：
sudo rm -f /etc/systemd/system/documize.service
sudo systemctl daemon-reload
sudo rm -rf /opt/documize
删除数据库与角色（确认无其他业务在用）：
sudo -u postgres psql -c "DROP DATABASE documize;"
sudo -u postgres psql -c "DROP ROLE documize;"
删除系统账号：
sudo userdel documize
验证清理结果：
ss -ltn | grep 8139 || echo "8139 released"
sudo -u postgres psql -tAc "select datname from pg_database where datname='documize';"
实测回显：
8139 released
⚠️ 注意：卸载前务必备份数据库；Documize 的所有文档与权限都在库里，删库即删全部内容。
八、参考链接
- Documize v5.14.0 Releases：https://github.com/documize/community/releases/tag/v5.14.0
- Documize 官方仓库 README：https://github.com/documize/community
- PostgreSQL 16 官方文档：https://www.postgresql.org/docs/16/
- 站内 PostgreSQL 参考：《PostgreSQL 18.6 介绍与选型指南》、《PostgreSQL 18 配置参数详解》
- 站内同类知识库参考：《Docspell 介绍与选型指南》、《Gitit 介绍与选型指南》、《LeafWiki 介绍与选型指南》