Wiki-Go 1.9.2 Docker Compose 与二进制部署指南

目标：在 Ubuntu 22.04 服务器上把 Wiki-Go 1.9.2 以官方支持的两种形态（Docker Compose 编排、release 预编译二进制）从 0 到 1 部署到「可登录、可建页、数据可持久化」，并给出双形态甄别与取舍结论。全部命令与回显实测于 2026-11-02。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
组件版本：Wiki-Go v1.9.2（GitHub Releases 最新正式版，2026-09-22 发布）
Compose 形态：官方发布标签 leomoonstudios/wiki-go:1.9.2（发布件磁盘占用 83.7 MB / 内容 20.9 MB，docker images 实测；官方制品同时声明 8080/443 两个服务端口，README 说明两种运行场景二选一）
二进制：wiki-go-linux-amd64，47294710 字节，sha256 7078219501a1467abde2c5ace0e1dabbc1bee125b20ff64f3ad131ab0cc07ba8（实测）
服务进程运行身份：Compose 形态固定 uid=1000(appuser) gid=1000(appgroup)（id 实测）；二进制形态以启动它的普通用户身份运行
监听：默认 0.0.0.0:8080（HTTP），TLS 由 server.ssl 或前置反代理实现
数据目录：Compose 形态 ./data 挂载到服务内 /wiki/data；二进制形态为进程工作目录下 ./data
默认账号：admin / admin（本指南第五节演示改为 q1w2e3r4）
版本实测：Docker version 29.9.2, build a82e528、Docker Compose version v5.6.1

二、部署形态甄别与选型说明

2.1 官方支持面

Wiki-Go 官方 README 特性栏第一条即「快速安装（官方 Compose 编排或预编译二进制）」，并随仓库提供 docker-compose-http.yml / docker-compose-ssl.yml 两套编排；Releases 每个版本附 11 个平台的预编译二进制。即 Compose 编排与裸二进制是并列的官方推荐形态，本文双形态均实测走通后给出取舍结论。

2.2 双实例并存甄别实录（重要前车之鉴）

实测期在宿主机上同时发现一个以 ./wiki-go 命令启动的残留进程，以及另一处在 8080 上的监听，疑似双实例并存。处置前先按「进程 → 端口 → 工作目录」三步归因，而不是看到相似进程名就直接 kill：

pgrep -af '^\./wiki-go'
ss -ltnp | grep ':8080'
readlink /proc/$(pgrep -of '^\./wiki-go')/cwd

3610 ./wiki-go
LISTEN 0 511 127.0.0.1:8080 0.0.0.0:* users:(("trae-cn",pid=6423,fd=73))
/wiki

回显说明 8080 当前由另一个进程持有，./wiki-go 进程的工作目录为 /wiki；两个进程各占一份运行环境，并未互斥同一端口。结论与告诫：

看到同名进程先用工作目录、端口归属和启动时间归因，再决定是否处置；
绝不能让两个 Wiki-Go 实例同时读写同一份 data 目录：配置自动补全、版本快照、备份作业都是本地文件操作，双实例会造成配置分叉与秒级时间戳快照互相覆盖（见 6.3）。

2.3 形态对照与选择建议

维度	Compose 形态	二进制形态
制品	官方发布件 83.7 MB（磁盘）	47 MB 单文件
运行时身份	固定 appuser uid 1000	启动用户
升级	换发布标签 `docker compose pull`	换二进制文件重启
数据目录	`./data` 挂载到 `/wiki/data`	工作目录 `./data` 自动生成
首启行为	发布件不内置 data，挂载空目录后自动生成 config.yaml	无 config 时自动生成并内置 admin/admin（实测日志见 5.2）
托管	compose `restart: unless-stopped`	systemd unit
TLS	443 端口 + ssl compose 变体，或反代	`server.ssl` 原生 TLS，或反代
适合	快速起站/多实例隔离/已具备 Compose 的机群	未安装 Compose 的裸机、嵌入式、s390x 等小众架构

建议：常规服务器首选 Compose（官方编排开箱即用、升级原子化）；无 Compose 运行环境的机器或需要 systemd 精细资源管控时用二进制。以下两形态都完整走 0→1。

三、前置条件

服务器具备 8080（或自选端口）空闲；
Compose 形态：已装 Docker 引擎（含 compose 插件）；二进制形态：glibc 环境即可（静态 Go 二进制，无其他依赖）；
工作目录约定：/opt/wiki-go/（本文示例统一使用）。

mkdir -p /opt/wiki-go/data && cd /opt/wiki-go

⚠️ 网络说明：本文下载环节涉及 GitHub。实测（2026-11-02）api.github.com 与 raw.githubusercontent.com 直连可用（HTTP 200），但 Releases 资产下载 URL 直连超时（http:000），走代理 192.168.1.72:7897 实测 200 可用；Compose 制品的拉取由守护进程既有代理通道完成。若你的环境官方直连不通，按 5.1 的代理写法执行。

四、形态一：Docker Compose 部署

4.1 发布标签选型说明

使用官方发布制品 leomoonstudios/wiki-go。Docker Hub 实测 label 序列：latest, 1.9, 1, 1.9.2, 1.9.1, 1.9.0, 1.8, 1.8.13 … 1.8.6，与 GitHub Releases 一一对应。生产建议钉具体版本（本文 1.9.2），避免 latest 漂移。

4.2 获取官方编排文件

官方仓库自带 docker-compose-http.yml（纯 HTTP 场景，README 推荐入口）：

curl -sLO https://raw.githubusercontent.com/leomoon-studios/wiki-go/master/docker-compose-http.yml

内容（实查）：

services:
  wiki-go:
    # Plain HTTP setup. Container exposes 8080.
    #   • Use directly  (http://localhost:8080)
    #   • Or put Nginx/Traefik/Caddy in front for TLS termination.
    #     Remember to set allow_insecure_cookies: true in config.yaml
    image: leomoonstudios/wiki-go:latest
    container_name: wiki-go
    ports:
      - "8080:8080"  # host:container
    volumes:
      - ./data:/wiki/data
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

把 image 钉为 leomoonstudios/wiki-go:1.9.2 后使用。

4.3 启动与验证

docker compose -f docker-compose-http.yml up -d

 Network wiki-go_default Creating
 Network wiki-go_default Created
 Container wiki-go Creating
 Container wiki-go Created
 Container wiki-go Starting
 Container wiki-go Started

docker compose ps

NAME      IMAGE                          COMMAND       SERVICE   CREATED        STATUS        PORTS
wiki-go   leomoonstudios/wiki-go:1.9.2   "./wiki-go"   wiki-go   3 seconds ago  Up 3 seconds  443/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

首页可达性验证：

curl -s -o /dev/null -w 'http:%{http_code}\n' http://127.0.0.1:8080/

http:200

4.4 首启自动生成配置与明文 HTTP 必改项

首次启动挂载的是空目录，Wiki-Go 自动生成 ./data/config.yaml。裸 HTTP 访问必须打开 insecure cookie（官方 README 明确提示），否则会话 Cookie 的 Secure 属性使浏览器/客户端无法在 HTTP 下回传：

sed -i 's/allow_insecure_cookies: false/allow_insecure_cookies: true/' data/config.yaml
docker compose restart

配置生效核对与 Cookie 属性对照（netscape jar 第 4 列即 secure 标志）：

grep -n allow_insecure_cookies data/config.yaml
curl -s -c jar -X POST http://127.0.0.1:8080/api/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"admin","keepLoggedIn":false}'

8:    allow_insecure_cookies: true
{"message":"Login successful","success":true}

127.0.0.1	FALSE	/	FALSE	1796196822	session_user	admin
#HttpOnly_127.0.0.1	FALSE	/	FALSE	1796196822	session_token	hG7YcXkUI0WHefLbCYa3Y8mNXJi6vm7oPjiPfcjq1x4=

4.5 登录改密与数据落盘验证

curl -s -b jar -X POST http://127.0.0.1:8080/api/password -H 'Content-Type: application/json' -d '{"current_password":"admin","new_password":"q1w2e3r4"}'

{"logged_out":true,"message":"User password updated successfully","redirect":"/login","success":true}

改密后旧会话立即失效（实测 401），重新登录：

curl -s -c jar -X POST http://127.0.0.1:8080/api/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4"}'
curl -s -b jar http://127.0.0.1:8080/api/check-auth

{"message":"Login successful","success":true}
{"groups":null,"role":"admin","success":true,"username":"admin"}

持久化验证（平面文件的核心承诺）：停止并重新启动服务后数据仍在：

docker compose down && docker compose -f docker-compose-http.yml up -d
curl -s -c jar -X POST http://127.0.0.1:8080/api/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4"}' >/dev/null
curl -s -b jar http://127.0.0.1:8080/api/check-auth

{"groups":null,"role":"admin","success":true,"username":"admin"}

宿主侧数据树核对：

ls data/

backups  comments  config.yaml  documents  pages  static  temp  versions

⚠️ 权限注意：官方制品内进程以 uid=1000(appuser) 运行，宿主数据目录必须对该 uid 可写（实测宿主属主 uid 1000 时读写正常）。若宿主 data 属主不是 1000，chown 1000:1000 data 后再启动。

4.6 环境变量与配置文件挂载说明

官方 compose 未注入任何环境变量；Wiki-Go 唯一的环境变量入口是 CONFIGFILE（源码 GetEnvString("CONFIGFILE", ...)，实测标志 -configfile 同源），默认值 data/config.yaml。如需把配置文件放在别处，两种等价做法：

    environment:
      - CONFIGFILE=/wiki/data/config.yaml   # 或命令行等价物：./wiki-go -configfile /path/config.yaml

参数详解见《Wiki-Go 1.9.2 配置参数详解》。

4.7 常用运维命令

docker compose logs --tail 20 wiki-go          # 查看服务日志（启动行为 `HTTP server starting on 0.0.0.0:8080...`）
ls data                                          # 在宿主机直接核对数据树（挂载目录同源）
docker compose -f docker-compose-http.yml restart   # 改配置后重启
docker compose -f docker-compose-http.yml down      # 停止并移除服务（挂载数据不动）

五、形态二：release 二进制部署

5.1 下载与校验

官方 Releases 页面选择 wiki-go-linux-amd64（v1.9.2）。直连与降级渠道实测情况见第三节 ⚠️ 说明：

# 官方 URL（本环境直连超时），代理渠道实测可用：
curl -x http://192.168.1.72:7897 -LO https://github.com/leomoon-studios/wiki-go/releases/download/v1.9.2/wiki-go-linux-amd64
sha256sum wiki-go-linux-amd64

7078219501a1467abde2c5ace0e1dabbc1bee125b20ff64f3ad131ab0cc07ba8  wiki-go-linux-amd64

mv wiki-go-linux-amd64 wiki-go && chmod +x wiki-go

5.2 零配置首启（实测行为）

在空目录直接启动（-configfile 默认 data/config.yaml）：

./wiki-go

实测全新工作目录首启完整日志（自动生成首页/样式/favicon，随后常驻）：

2026/11/02 17:24:13 [INFO] Config file data/config.yaml not found, skipping user-role migration
2026/11/02 17:24:14 [INFO] Created default homepage at data/pages/home/document.md
2026/11/02 17:24:14 [INFO] Created default custom.css file at data/static/custom.css
2026/11/02 17:24:14 [INFO] Created default custom.js file at data/static/custom.js
2026/11/02 17:24:14 [INFO] Copied default static file to data/static/favicon.ico
2026/11/02 17:24:14 [INFO] Copied default static file to data/static/favicon.png
2026/11/02 17:24:14 [INFO] Copied default static file to data/static/favicon.svg
2026/11/02 17:24:14 [INFO] HTTP server starting on 0.0.0.0:8080...

首启生成 data/ 目录（实测 ls data → config.yaml pages static temp），并在 config.yaml 自动生成 admin 用户段（bcrypt 哈希，实测样本）：

users:
    - username: admin
      password: $2a$14$8O0RQmPZ6jfWDx7I6w0xuOsFmPON98bQ6L.S1pc1g1LkmQwzZy.Pu
      role: admin

登录验证（默认口令 admin/admin）：

curl -s -c jar -X POST http://127.0.0.1:8080/api/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"admin"}'

{"message":"Login successful","success":true}

5.3 端口修改与冲突处置（实测报错）

默认端口被占时首启即报错退出（实测两种场景：与另一实例同机抢 8080、宿主端口被占）：

2026/11/02 07:34:58 [ERROR] HTTP server error: listen tcp 0.0.0.0:8080: bind: address already in use

改法：编辑 data/config.yaml：

server:
    host: "0.0.0.0"
    port: 8145

重启后实测日志：

2026/11/02 15:44:36 [INFO] HTTP server starting on 0.0.0.0:8145...

5.4 systemd 托管

创建 /etc/systemd/system/wiki-go.service：

[Unit]
Description=Wiki-Go flat-file wiki
After=network.target

[Service]
Type=simple
User=wiki
Group=wiki
WorkingDirectory=/opt/wiki-go
ExecStart=/opt/wiki-go/wiki-go -configfile /opt/wiki-go/data/config.yaml
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

⚠️ systemd 托管需在带 systemd 的 Linux 真机执行（本次实测载体以后台进程等效验证了启动/配置/回滚全链路，unit 文件按官方启动参数 -configfile 编写）。

启用与验证：

systemctl daemon-reload
systemctl enable wiki-go
systemctl start wiki-go
systemctl is-active wiki-go

active

curl -s -o /dev/null -w 'http:%{http_code}\n' http://127.0.0.1:8080/

http:200

5.5 升级与回滚（二进制形态）

# 升级：拉新 SHA256 对照 Release Notes 后替换
curl -x http://192.168.1.72:7897 -LO https://github.com/leomoon-studios/wiki-go/releases/download/<新版本>/wiki-go-linux-amd64
systemctl stop wiki-go
mv wiki-go-linux-amd64 wiki-go.new && chmod +x wiki-go.new
mv wiki-go wiki-go.bak && mv wiki-go.new wiki-go
systemctl start wiki-go
systemctl is-active wiki-go

平面文件目录结构跨版本兼容（v1.9.2 直接读取低版本 data 树，配置缺失键自动补全，见《Wiki-Go 1.9.2 配置参数详解》的 ensureCompleteConfig 行为）；回滚即换回 wiki-go.bak。

六、TLS 与反代说明

官方提供第二条编排路线 docker-compose-ssl.yml（宿主 443 → 服务 443，挂载证书/私钥），配合 config.yaml 开启原生 TLS：

server:
    ssl: true
    ssl_cert: "/wiki/certs/cert.pem"
    ssl_key:  "/wiki/certs/key.pem"

证书/私钥为敏感文件，按固定路径 /etc/wiki-go/certs/cert.pem、/etc/wiki-go/certs/key.pem 存放，并在编排中挂载：

    volumes:
      - ./data:/wiki/data
      - /etc/wiki-go/certs:/wiki/certs:ro

对应 config.yaml 写 ssl_cert: "/wiki/certs/cert.pem"、ssl_key: "/wiki/certs/key.pem"。官方 README 同时说明：发布件声明 8080 与 443 双端口，按运行场景二选一。本文实测走的是 HTTP 形态（allow_insecure_cookies: true 即为该形态服务）；走 Nginx 反代 + TLS 终结时，务必把 server.trusted_proxies 只填反代来源地址（README 示例：单机 Nginx proxy_pass http://127.0.0.1:PORT 时填 ["127.0.0.1"]），并保持 allow_insecure_cookies: false。

七、常见问题（FAQ）

7.1 明文 HTTP 下登录成功但下一秒就 401

会话 Cookie 默认带 Secure 属性，HTTP 下不回传。改 allow_insecure_cookies: true 并重启（4.4 实测）。仅可信内网开启。

7.2 8080 被占起不来

见 5.3 实测报错；改 server.port 或停掉占用进程。同一 data 目录严禁双实例并跑（2.2）。

7.3 bind mount 目录写不进

服务进程以 uid=1000 运行，宿主 data 需 chown 1000:1000（4.5 ⚠️ 说明）。

7.4 连续输错密码后 429

默认防爆破：180 秒窗口 5 次失败封 60 秒起，最长 24 小时（实测回显 {"message":"Too many failed logins; try again later","retryAfter":60,"success":false}），参数可调（见配置详解）。封禁期间正确密码也拒绝（实测 429）。

7.5 Releases 下载不动

GitHub Releases 资产直连在本环境超时，代理实测可用（5.1）；二进制亦可从官方在线 Demo/CI 产物渠道获取，务必核对 sha256。

八、卸载与清理

# Compose 形态
docker compose -f docker-compose-http.yml down
docker image rm leomoonstudios/wiki-go:1.9.2
rm -rf /opt/wiki-go/data          # 数据即目录，删前确认已备份（备份 zip 可从管理界面导出）
# 二进制形态
systemctl disable --now wiki-go
rm /etc/systemd/system/wiki-go.service && systemctl daemon-reload
rm -rf /opt/wiki-go

九、参考链接

官方仓库与 README：https://github.com/leomoon-studios/wiki-go
Releases：https://github.com/leomoon-studios/wiki-go/releases
Docker Hub：https://hub.docker.com/r/leomoonstudios/wiki-go
组件介绍与选型：《Wiki-Go 1.9.2 介绍与选型指南》
配置项逐一详解：《Wiki-Go 1.9.2 配置参数详解》
部署后 API 验收：《Wiki-Go 1.9.2 API 使用详解》