From 41d5f0a3ee7045516f7f89d36f5377e31f1a14b6 Mon Sep 17 00:00:00 2001
From: FenjuFu <fufenjupku@gmail.com>
Date: Tue, 8 Sep 2026 17:26:57 +0800
Subject: [PATCH] docs(faq): document runtime.sh for China / intranet
 deployments

Users hand-writing a compose file for intranet installs hit database init and
dependency-order errors. Point them at the official runtime.sh entrypoint,
including the --aliyun mirror for networks that cannot reach ghcr.io and the
mirror-runtime-images.sh + --mirror-registry path for air-gapped setups.
Applied to both the zh and en reference FAQ.

Signed-off-by: FenjuFu <fufenjupku@gmail.com>
---
 document/docs/05-reference/faq.md                  | 14 ++++++++++++++
 .../current/05-reference/faq.md                    | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/document/docs/05-reference/faq.md b/document/docs/05-reference/faq.md
index 94c5ea4c..a911c26f 100644
--- a/document/docs/05-reference/faq.md
+++ b/document/docs/05-reference/faq.md
@@ -20,6 +20,20 @@ description: 常见问题解答
 
 使用 PostgreSQL 标准备份工具（pg_dump）。
 
+### 国内 / 内网环境部署时镜像拉取失败，或自己拼 compose 启动数据库报错？
+
+优先使用官方的 `runtime.sh` 一键脚本，而不是手写 compose：
+
+```bash
+# 默认从 ghcr.io 拉取镜像
+curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com
+
+# 国内网络拉不到 ghcr.io 时，加 --aliyun 走阿里云镜像源
+curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest
+```
+
+脚本会自动准备 PostgreSQL、Redis、对象存储等依赖并按正确顺序启动，能避免手写 compose 时常见的数据库初始化 / 依赖顺序报错。完全离线的环境可先用 `scripts/mirror-runtime-images.sh` 把镜像同步到内网 registry，再用 `--mirror-registry <地址>` 指向它。
+
 ## 使用相关
 
 ### 如何重置管理员密码？
diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md
index 04ec69b8..dac50ffb 100644
--- a/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md
+++ b/document/i18n/en/docusaurus-plugin-content-docs/current/05-reference/faq.md
@@ -20,6 +20,20 @@ Recommended to use reverse proxy (Nginx/Ingress) for TLS termination.
 
 Use PostgreSQL standard backup tools (pg_dump).
 
+### Image pull fails when deploying in China / an intranet, or the database errors when hand-writing compose?
+
+Prefer the official one-line `runtime.sh` script over a hand-written compose file:
+
+```bash
+# Pull images from ghcr.io (default)
+curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com
+
+# If ghcr.io is unreachable in China, add --aliyun to use the Aliyun mirror
+curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest
+```
+
+The script provisions PostgreSQL, Redis and object storage and starts them in the right order, avoiding the database-init / dependency-order errors that commonly appear with a hand-written compose. For fully air-gapped environments, first sync the images to an internal registry with `scripts/mirror-runtime-images.sh`, then point to it with `--mirror-registry <addr>`.
+
 ## Usage Related
 
 ### How to reset admin password?