fix(cloud-image): make firstboot idempotent and pin image versions

Address review feedback on PR #1249:

- prepare.sh: when WEKNORA_REF looks like a version tag (v*), write the
  matching WEKNORA_VERSION into .env so docker compose pulls images that
  match the compose YAML's git ref (previously stuck on :latest).
- prepare.sh: detect docker binary path via `command -v docker` and
  template it into weknora.service (replacing hardcoded /usr/bin/docker
  that fails when docker lives in /usr/local/bin).
- firstboot.sh: write a /opt/WeKnora/.firstboot.done marker immediately
  after rewriting .env, before `docker compose up -d`. If compose fails
  mid-run, the next boot is gated by ConditionPathExists=!marker so we
  never regenerate DB_PASSWORD against an already-initialized postgres
  volume (which previously bricked the database).
- firstboot.sh: stop deleting its own unit file / script while the
  oneshot is still executing; rely on the marker + `systemctl disable`
  instead, avoiding "job failed" markings from systemd.
- firstboot.sh: use detected docker path instead of /usr/bin/docker;
  add note in credentials file that .env is the source of truth.
- weknora-firstboot.service: add ConditionPathExists=!.firstboot.done.
- cleanup.sh: scope docker volume deletion to compose project label
  (com.docker.compose.project=<name>) instead of fuzzy substring match
  that could nuke unrelated postgres/redis volumes.
- cleanup.sh: also remove .firstboot.done marker, firstboot log, and
  any leftover /root/weknora-credentials.txt so the image is clean.
- README.md: clarify how to actually disable registration (edit the
  `replace` call list in firstboot.sh, not run that command in shell).
This commit is contained in:
wizardchen
2026-05-11 12:12:29 +08:00
committed by lyingbug
parent 155f3b3e72
commit cdfbf05524
6 changed files with 75 additions and 18 deletions
+1 -1
View File
@@ -204,7 +204,7 @@ sudo bash /opt/weknora-tools/scripts/cloud-image/cleanup.sh
之后每次开机都由 `weknora.service` 接管。
> **注意**:`firstboot.sh` 默认**不**禁用注册(`DISABLE_REGISTRATION=false`),第一个注册的人会成为管理员。
> 凭证文件里有「请尽快注册以防被抢注」的醒目提示。需要更严格控制可在 `firstboot.sh` 里把这一行 `replace DISABLE_REGISTRATION true`。
> 凭证文件里有「请尽快注册以防被抢注」的醒目提示。需要更严格控制可在 `firstboot.sh` 的 `replace` 调用列表中追加一行 `replace DISABLE_REGISTRATION true` 后再重制镜像。
---
+12 -4
View File
@@ -18,21 +18,29 @@ if [[ "${ans}" != "YES" ]]; then
fi
echo "[cleanup] 1/8 停止 WeKnora 容器"
COMPOSE_PROJECT=""
if [[ -d "${WEKNORA_DIR}" ]]; then
cd "${WEKNORA_DIR}"
# 优先用 compose ls 拿到真实 project 名 (默认是目录名小写, 如 weknora)
COMPOSE_PROJECT="$(docker compose ls --format json 2>/dev/null \
| grep -oE '"Name":"[^"]+"' | head -1 | cut -d'"' -f4 || true)"
docker compose down -v --remove-orphans || true
fi
echo "[cleanup] 2/8 清空 WeKnora 业务数据"
echo "[cleanup] 2/8 清空 WeKnora 业务数据 + 首启 marker / 日志"
if [[ -d "${WEKNORA_DIR}" ]]; then
rm -rf "${WEKNORA_DIR}/data"/* "${WEKNORA_DIR}/logs"/* 2>/dev/null || true
rm -f "${WEKNORA_DIR}/.env"
rm -f "${WEKNORA_DIR}/.env" "${WEKNORA_DIR}/.firstboot.done"
cp "${WEKNORA_DIR}/.env.example" "${WEKNORA_DIR}/.env"
fi
rm -f /root/weknora-credentials.txt /var/log/weknora-firstboot.log
echo "[cleanup] 3/8 清理残留 docker 卷与构建缓存"
docker volume ls -q | grep -Ei 'weknora|postgres|redis|minio|qdrant|elasticsearch|milvus|weaviate' \
| xargs -r docker volume rm -f || true
# 严格按 compose project 名前缀匹配, 避免误伤同宿主上其它 postgres/redis 卷。
if [[ -n "${COMPOSE_PROJECT}" ]]; then
docker volume ls -q --filter "label=com.docker.compose.project=${COMPOSE_PROJECT}" \
| xargs -r docker volume rm -f || true
fi
docker system prune -af --volumes || true
echo "[cleanup] 4/8 清空系统日志"
+36 -11
View File
@@ -1,21 +1,41 @@
#!/usr/bin/env bash
# firstboot.sh - 由 weknora-firstboot.service 在新实例首次开机时自动执行。
# 任务: 生成随机密钥写入 .env -> 启动容器 -> 输出凭证 -> 自删除。
# 任务: 生成随机密钥写入 .env -> 启动容器 -> 输出凭证 -> 标记完成 + 自禁用。
#
# 幂等性策略:
# 1) 一上来先写 ${MARKER} 标记 "已生成过密钥",
# 之后即便 docker compose 失败导致脚本中断, 重启后由 unit 的
# ConditionPathExists=!${MARKER} 拦住, 不会再生成新密钥覆盖 .env。
# (旧密钥已经写进 postgres 数据卷, 二次生成会导致数据库永久无法登录)
# 2) 失败时 unit 标记 failed, 用户可手动 docker compose up -d 恢复;
# 凭证仍可在 ${ENV_FILE} 中查到。
set -euo pipefail
WEKNORA_DIR="${WEKNORA_DIR:-/opt/WeKnora}"
ENV_FILE="${WEKNORA_DIR}/.env"
CRED_FILE="/root/weknora-credentials.txt"
LOG_FILE="/var/log/weknora-firstboot.log"
MARKER="${WEKNORA_DIR}/.firstboot.done"
exec >>"${LOG_FILE}" 2>&1
echo "==== firstboot started at $(date -Iseconds) ===="
if [[ -f "${MARKER}" ]]; then
echo "marker ${MARKER} exists, skip (already initialized)"
exit 0
fi
if [[ ! -f "${ENV_FILE}" ]]; then
echo "ERROR: ${ENV_FILE} not found"
exit 1
fi
DOCKER_BIN="$(command -v docker || true)"
if [[ -z "${DOCKER_BIN}" ]]; then
echo "ERROR: docker binary not found in PATH"
exit 1
fi
# 生成 32 字节强随机字符串(用于 AES-256 key, 必须刚好 32 字节)
gen32() { LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32; }
# 通用密码: 24 字符, 不含 / + = (避免出现在 URL / sed 替换时出问题)
@@ -44,16 +64,22 @@ replace SYSTEM_AES_KEY "${SYS_AES}"
replace TENANT_AES_KEY "${TENANT_AES}"
replace GIN_MODE "release"
echo "env updated, starting docker compose..."
# 关键: .env 改完立刻写 marker。
# 这之后即便 docker compose up 失败, 重启也不会再次重写 .env,
# 防止与 postgres 已经持久化的密码不一致。
umask 077
touch "${MARKER}"
chmod 0600 "${MARKER}"
echo "env updated, marker written, starting docker compose..."
cd "${WEKNORA_DIR}"
/usr/bin/docker compose up -d
"${DOCKER_BIN}" compose up -d
# 尝试拿公网 IP, 失败就用内网
PUB_IP=$(curl -fsS --max-time 5 https://ifconfig.me 2>/dev/null \
|| curl -fsS --max-time 5 https://api.ipify.org 2>/dev/null \
|| hostname -I | awk '{print $1}')
umask 077
cat >"${CRED_FILE}" <<INFO
========================================
WeKnora 实例初始化完成
@@ -73,18 +99,17 @@ cat >"${CRED_FILE}" <<INFO
SYSTEM_AES_KEY = ${SYS_AES}
TENANT_AES_KEY = ${TENANT_AES}
安全建议:
- 切勿直接对外暴露 5432 / 6379 / 9000 等基础设施端口
- 仅用 80 / 443 对外服务, 必要时配置反向代理 + HTTPS
注意:
- 本文件只反映首启时刻的密钥, 后续以 ${ENV_FILE} 为准。
- 切勿直接对外暴露 5432 / 6379 / 9000 等基础设施端口。
- 仅用 80 / 443 对外服务, 必要时配置反向代理 + HTTPS。
INFO
echo "credentials written to ${CRED_FILE}"
# 自删除: 关掉 unit + 删脚本 + 删 unit 文件
# 仅停掉 unit, 不删 unit 文件 (否则当前正在运行的 oneshot 可能被 systemd 标记 failed)。
# 下次重启时, weknora-firstboot.service 通过 ConditionPathExists=!${MARKER} 自动跳过。
systemctl disable weknora-firstboot.service || true
rm -f /etc/systemd/system/weknora-firstboot.service
rm -f /usr/local/sbin/weknora-firstboot.sh
systemctl daemon-reload || true
echo "==== firstboot finished at $(date -Iseconds) ===="
+23
View File
@@ -73,6 +73,18 @@ cd "${WEKNORA_DIR}"
[[ -f .env ]] || cp .env.example .env
sed -i 's/^GIN_MODE=.*/GIN_MODE=release/' .env || true
# 若 WEKNORA_REF 形如 v1.2.3, 把同名版本号写到 .env 的 WEKNORA_VERSION,
# 让 docker compose 拉取与 ref 对齐的镜像 tag, 避免 ref/image 版本错配。
if [[ "${WEKNORA_REF}" =~ ^v[0-9] ]]; then
WEKNORA_VERSION_VAL="${WEKNORA_REF#v}"
if grep -qE '^WEKNORA_VERSION=' .env; then
sed -i "s|^WEKNORA_VERSION=.*|WEKNORA_VERSION=${WEKNORA_VERSION_VAL}|" .env
else
echo "WEKNORA_VERSION=${WEKNORA_VERSION_VAL}" >>.env
fi
echo "[prepare] -> WEKNORA_VERSION=${WEKNORA_VERSION_VAL}"
fi
echo "[prepare] 4/6 拉取并启动默认 5 个常驻容器 (frontend/app/docreader/postgres/redis)"
docker compose pull
docker compose up -d
@@ -87,10 +99,21 @@ docker compose --profile full pull sandbox || true
# cd /opt/WeKnora && docker compose --profile <name> up -d
echo "[prepare] 5/6 安装 systemd 单元"
# 探测 docker 二进制路径, 不同发行版可能在 /usr/bin 或 /usr/local/bin
DOCKER_BIN="$(command -v docker)"
if [[ -z "${DOCKER_BIN}" ]]; then
echo "[prepare] 未找到 docker 二进制" >&2
exit 1
fi
echo "[prepare] docker binary: ${DOCKER_BIN}"
install -m 0644 "${SCRIPT_DIR}/systemd/weknora.service" /etc/systemd/system/weknora.service
install -m 0644 "${SCRIPT_DIR}/systemd/weknora-firstboot.service" /etc/systemd/system/weknora-firstboot.service
install -m 0755 "${SCRIPT_DIR}/firstboot.sh" /usr/local/sbin/weknora-firstboot.sh
# 把 systemd 单元里的 docker 路径模板替换为实际路径
sed -i "s|@DOCKER_BIN@|${DOCKER_BIN}|g" /etc/systemd/system/weknora.service
systemctl daemon-reload
systemctl enable weknora.service
systemctl enable weknora-firstboot.service
@@ -5,6 +5,7 @@ Requires=docker.service
Wants=network-online.target
Before=weknora.service
ConditionPathExists=/usr/local/sbin/weknora-firstboot.sh
ConditionPathExists=!/opt/WeKnora/.firstboot.done
[Service]
Type=oneshot
+2 -2
View File
@@ -8,8 +8,8 @@ Wants=network-online.target
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/WeKnora
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
ExecStart=@DOCKER_BIN@ compose up -d
ExecStop=@DOCKER_BIN@ compose down
TimeoutStartSec=600
[Install]