Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

feat(docker): improve installer diagnostics

tianma-if5566af151f95
diff --git a/README.md b/README.md
index 098f587c..f027464b 100644
--- a/README.md
+++ b/README.md
@@ -94,16 +94,23 @@ Complete setup in 5 simple web steps:
### Option C: Docker on a VPS or NAS
+For a VPS or NAS outside mainland China, use the GitHub-hosted installer and
+GHCR image:
+
```sh
curl -fsSL https://edgeever.org/install.sh | bash
```
-The script pulls the latest image, generates an administrator password, and starts EdgeEver with Docker Compose. Users in mainland China can use the Tencent COS and TCR mirrors:
+For a VPS or NAS located in mainland China, use the Tencent COS installer and
+Tencent TCR image for faster, more reliable downloads:
```sh
curl -fsSL https://edgeever-installer-1256854452.cos.ap-guangzhou.myqcloud.com/install.sh | bash -s -- --mirror tcr
```
+Both commands pull the latest image, generate an administrator password, and
+start EdgeEver with Docker Compose.
+
See the [Docker deployment guide](docs/deploy-docker.md) for manual deployment and configuration.
---
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 24e3dcf4..8f30f2f2 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -94,11 +94,21 @@ Cloudflare 在线部署可以选择以下两种方式之一:
### 方案三:在 VPS 或 NAS 上使用 Docker
+如果 VPS 或 NAS 位于中国大陆境外,使用 GitHub 托管的安装脚本和 GHCR 镜像:
+
+```sh
+curl -fsSL https://edgeever.org/install.sh | bash
+```
+
+如果 VPS 或 NAS 位于中国大陆境内,使用腾讯云 COS 安装脚本和腾讯云 TCR 镜像,
+下载速度和稳定性通常更好:
+
```sh
curl -fsSL https://edgeever-installer-1256854452.cos.ap-guangzhou.myqcloud.com/install.sh | bash -s -- --mirror tcr
```
-脚本和 Compose 配置由腾讯云 COS 提供中国大陆入口,并自动从腾讯云 TCR 拉取最新镜像、生成管理员密码及启动 EdgeEver。手动部署与配置说明见 [Docker 部署文档](docs/deploy-docker.zh-CN.md)。
+两种方式都会自动拉取最新镜像、生成管理员密码,并使用 Docker Compose 启动
+EdgeEver。手动部署与配置说明见 [Docker 部署文档](docs/deploy-docker.zh-CN.md)。
---
diff --git a/apps/site/public/install.sh b/apps/site/public/install.sh
index 8c9f0e44..1f8bca66 100755
--- a/apps/site/public/install.sh
+++ b/apps/site/public/install.sh
@@ -19,6 +19,21 @@ project_name="${EDGE_EVER_PROJECT_NAME:-edgeever}"
generated_password=false
temporary_compose=""
temporary_env=""
+current_step="Parse arguments"
+diagnostics_printed=false
+start_epoch=0
+declare -a compose=()
+
+log() {
+ local level="$1"
+ shift
+ printf '[%s] [%-7s] %s\n' "$(date '+%H:%M:%S')" "$level" "$*" >&2
+}
+
+step() {
+ current_step="$2"
+ log "STEP $1/6" "$2"
+}
usage() {
cat <<'EOF'
@@ -43,14 +58,37 @@ EDGE_EVER_AUTH_PASSWORD.
EOF
}
+print_diagnostics() {
+ [[ "$diagnostics_printed" == false ]] || return 0
+ diagnostics_printed=true
+
+ log ERROR "Stage: $current_step"
+ if ((${#compose[@]} > 0)); then
+ log INFO "Container status:"
+ "${compose[@]}" ps -a >&2 || true
+ log INFO "Recent container logs:"
+ "${compose[@]}" logs --tail 80 edgeever >&2 || true
+ log INFO "Troubleshooting commands:"
+ printf ' cd %q\n' "$install_dir" >&2
+ printf ' docker compose --project-name %q --env-file .env --file compose.yaml ps -a\n' "$project_name" >&2
+ printf ' docker compose --project-name %q --env-file .env --file compose.yaml logs --tail 200 edgeever\n' "$project_name" >&2
+ fi
+ log INFO "Deployment guide: https://github.com/tianma-if/edgeever/blob/main/docs/deploy-docker.md"
+}
+
fail() {
- printf 'EdgeEver installer: %s\n' "$*" >&2
+ trap - ERR
+ log ERROR "$*"
+ print_diagnostics
exit 1
}
on_error() {
local exit_code=$?
- printf 'EdgeEver installer: command failed at line %s\n' "${BASH_LINENO[0]}" >&2
+ local line_number="${BASH_LINENO[0]}"
+ trap - ERR
+ log ERROR "A command failed (exit code: $exit_code, line: $line_number)"
+ print_diagnostics
exit "$exit_code"
}
@@ -104,6 +142,8 @@ while [[ $# -gt 0 ]]; do
esac
done
+start_epoch="$(date '+%s')"
+step 1 "Validate environment"
[[ -n "$install_dir" ]] || fail "set HOME or EDGE_EVER_INSTALL_DIR"
[[ "$project_name" =~ ^[a-z0-9][a-z0-9_-]*$ ]] || fail "invalid EDGE_EVER_PROJECT_NAME"
@@ -111,10 +151,39 @@ command -v curl >/dev/null 2>&1 || fail "curl is required"
command -v docker >/dev/null 2>&1 || fail "Docker is required: https://docs.docker.com/engine/install/"
docker compose version >/dev/null 2>&1 || fail "Docker Compose v2 is required"
docker info >/dev/null 2>&1 || fail "cannot connect to the Docker daemon"
+log INFO "Docker and Docker Compose are available"
+
+host_os=""
+if [[ -r /etc/os-release ]]; then
+ while IFS='=' read -r key value; do
+ if [[ "$key" == "PRETTY_NAME" ]]; then
+ host_os="${value#\"}"
+ host_os="${host_os%\"}"
+ break
+ fi
+ done < /etc/os-release
+fi
+host_os="${host_os:-$(uname -s)}"
+kernel_version="$(uname -sr)"
+host_architecture="$(uname -m)"
+docker_engine_version="$(docker version --format '{{.Server.Version}}' 2>/dev/null || true)"
+docker_engine_version="${docker_engine_version:-unknown}"
+docker_compose_version="$(docker compose version --short 2>/dev/null || true)"
+docker_compose_version="${docker_compose_version:-unknown}"
+log INFO "Host OS: $host_os"
+log INFO "Kernel: $kernel_version"
+log INFO "Architecture: $host_architecture"
+log INFO "Docker Engine: $docker_engine_version"
+log INFO "Docker Compose: $docker_compose_version"
mkdir -p "$install_dir"
env_file="$install_dir/.env"
compose_file="$install_dir/compose.yaml"
+if [[ -f "$env_file" ]]; then
+ install_mode="upgrade"
+else
+ install_mode="new installation"
+fi
read_env_value() {
local key="$1"
@@ -135,6 +204,7 @@ read_env_value() {
return 1
}
+step 2 "Resolve configuration"
if [[ -z "$image" ]]; then
image="$(read_env_value EDGE_EVER_IMAGE || true)"
image="${image:-$GHCR_IMAGE}"
@@ -183,6 +253,11 @@ fi
[[ "$port" =~ ^[0-9]+$ ]] && ((port >= 1 && port <= 65535)) || fail "port must be between 1 and 65535"
[[ "$username" != *$'\n'* && "$username" != *"'"* ]] || fail "invalid administrator username"
[[ "$password" != *$'\n'* && "$password" != *"'"* ]] || fail "password must not contain a newline or single quote"
+log INFO "Mode: $install_mode"
+log INFO "Install directory: $install_dir"
+log INFO "EdgeEver target: $image:$version"
+log INFO "Compose source: $compose_url"
+log INFO "Published port: $port"
cleanup() {
[[ -z "$temporary_compose" || ! -e "$temporary_compose" ]] || rm -f "$temporary_compose"
@@ -191,13 +266,16 @@ cleanup() {
}
trap cleanup EXIT
+step 3 "Download Compose configuration"
temporary_compose="$(mktemp "$install_dir/.compose.yaml.XXXXXX")"
curl --fail --silent --show-error --location --output "$temporary_compose" "$compose_url"
grep -q '^services:' "$temporary_compose" || fail "downloaded Compose file is invalid"
chmod 0644 "$temporary_compose"
mv "$temporary_compose" "$compose_file"
temporary_compose=""
+log INFO "Saved Compose configuration to $compose_file"
+step 4 "Write runtime configuration"
temporary_env="$(mktemp "$install_dir/.env.XXXXXX")"
{
printf "EDGE_EVER_IMAGE='%s'\n" "$image"
@@ -209,6 +287,7 @@ temporary_env="$(mktemp "$install_dir/.env.XXXXXX")"
chmod 0600 "$temporary_env"
mv "$temporary_env" "$env_file"
temporary_env=""
+log INFO "Saved protected configuration to $env_file (password hidden)"
compose=(
docker compose
@@ -218,33 +297,43 @@ compose=(
--file "$compose_file"
)
-printf 'Pulling %s:%s...\n' "$image" "$version"
+step 5 "Pull image and start container"
"${compose[@]}" pull
"${compose[@]}" up -d --remove-orphans
+step 6 "Wait for health check"
container_id=""
health=""
-for _ in {1..60}; do
+for attempt in {1..60}; do
container_id="$("${compose[@]}" ps -q edgeever 2>/dev/null || true)"
if [[ -n "$container_id" ]]; then
health="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$container_id" 2>/dev/null || true)"
[[ "$health" == "healthy" ]] && break
[[ "$health" == "exited" || "$health" == "dead" ]] && break
fi
+ if ((attempt == 1 || attempt % 5 == 0)); then
+ log INFO "Waiting for container health (status: ${health:-not started}, elapsed: $((attempt * 2))s)"
+ fi
sleep 2
done
if [[ "$health" != "healthy" ]]; then
- "${compose[@]}" logs --tail 80 edgeever >&2 || true
fail "container did not become healthy (status: ${health:-unknown})"
fi
-printf '\nEdgeEver is ready.\n'
-printf 'URL: http://<server-ip>:%s\n' "$port"
-printf 'Username: %s\n' "$username"
+running_image="$(docker inspect --format '{{.Config.Image}}' "$container_id" 2>/dev/null || true)"
+log INFO "Running image: ${running_image:-$image:$version}"
+log SUCCESS "EdgeEver is ready ($(($(date '+%s') - start_epoch))s)"
+printf '\nConnection details\n'
+printf ' URL: http://<server-ip>:%s\n' "$port"
+printf ' Username: %s\n' "$username"
if [[ "$generated_password" == true ]]; then
- printf 'Password: %s\n' "$password"
+ printf ' Password: %s\n' "$password"
else
- printf 'Password: unchanged (stored in %s)\n' "$env_file"
+ printf ' Password: unchanged (stored in %s)\n' "$env_file"
fi
-printf 'Install directory: %s\n' "$install_dir"
+printf ' Install directory: %s\n' "$install_dir"
+printf '\nUseful commands\n'
+printf ' cd %q\n' "$install_dir"
+printf ' docker compose ps\n'
+printf ' docker compose logs --tail 200 -f edgeever\n'
diff --git a/scripts/docker-installer.test.mjs b/scripts/docker-installer.test.mjs
index e9fb565c..634950b5 100644
--- a/scripts/docker-installer.test.mjs
+++ b/scripts/docker-installer.test.mjs
@@ -1,5 +1,6 @@
import { describe, expect, test } from "bun:test";
import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { resolve } from "node:path";
@@ -9,6 +10,50 @@ const installerPath = resolve(projectRoot, "apps/site/public/install.sh");
const composePath = resolve(projectRoot, "compose.yaml");
const hostedComposePath = resolve(projectRoot, "apps/site/public/compose.yaml");
+function runInstaller(arguments_, environment) {
+ const harnessDirectory = mkdtempSync(resolve(tmpdir(), "edgeever-installer-harness-"));
+ const resultPath = resolve(harnessDirectory, "result.json");
+ try {
+ const harness = spawnSync(
+ "node",
+ [
+ "-e",
+ [
+ 'const { spawnSync } = require("node:child_process");',
+ 'const { writeFileSync } = require("node:fs");',
+ "const result = spawnSync(",
+ ' "/bin/bash",',
+ " [process.env.EDGE_EVER_TEST_INSTALLER, ...JSON.parse(process.env.EDGE_EVER_TEST_ARGUMENTS)],",
+ ' { encoding: "utf8", env: process.env },',
+ ");",
+ "writeFileSync(process.env.EDGE_EVER_TEST_RESULT, JSON.stringify({",
+ " status: result.status,",
+ " signal: result.signal,",
+ ' stdout: result.stdout || "",',
+ ' stderr: result.stderr || "",',
+ " error: result.error?.message,",
+ "}));",
+ ].join("\n"),
+ ],
+ {
+ env: {
+ ...environment,
+ EDGE_EVER_TEST_ARGUMENTS: JSON.stringify(arguments_),
+ EDGE_EVER_TEST_INSTALLER: installerPath,
+ EDGE_EVER_TEST_RESULT: resultPath,
+ },
+ encoding: "utf8",
+ },
+ );
+ if (harness.status !== 0) {
+ throw new Error(`installer test harness failed: ${harness.stderr}`);
+ }
+ return JSON.parse(readFileSync(resultPath, "utf8"));
+ } finally {
+ rmSync(harnessDirectory, { recursive: true, force: true });
+ }
+}
+
describe("Docker installer", () => {
test("publishes the repository Compose file unchanged", async () => {
expect(await readFile(hostedComposePath, "utf8")).toBe(await readFile(composePath, "utf8"));
@@ -30,7 +75,13 @@ describe("Docker installer", () => {
`#!/usr/bin/env bash
set -eu
printf '%s\\n' "$*" >> "$EDGE_EVER_TEST_DOCKER_LOG"
-if [[ "$1" == "inspect" ]]; then
+if [[ "$1" == "version" ]]; then
+ printf '27.5.1\\n'
+elif [[ "$1" == "compose" && "$2" == "version" && "\${3:-}" == "--short" ]]; then
+ printf '2.32.4\\n'
+elif [[ "$1" == "inspect" && "$*" == *".Config.Image"* ]]; then
+ printf 'ccr.ccs.tencentyun.com/edgeever/edgeever:latest\\n'
+elif [[ "$1" == "inspect" ]]; then
printf 'healthy\\n'
elif [[ "$1" == "compose" && "$*" == *" ps -q edgeever"* ]]; then
printf 'edgeever-test-container\\n'
@@ -65,15 +116,11 @@ cp "$EDGE_EVER_TEST_COMPOSE_SOURCE" "$output"
EDGE_EVER_TEST_CURL_LOG: curlLog,
EDGE_EVER_TEST_DOCKER_LOG: dockerLog,
};
- const first = spawnSync("bash", [installerPath, "--mirror", "tcr", "--port", "18789"], {
- env: environment,
- encoding: "utf8",
- stdio: ["ignore", "ignore", "pipe"],
- });
+ const first = runInstaller(["--mirror", "tcr", "--port", "18789"], environment);
if (first.status !== 0) {
const commands = await readFile(dockerLog, "utf8").catch(() => "no Docker commands");
throw new Error(
- `installer failed (exit=${first.status}, signal=${first.signal}):\n${first.stderr}\n${commands}`,
+ `installer failed (exit=${first.status}, signal=${first.signal}):\n${first.stdout}\n${first.stderr}\n${commands}`,
);
}
expect(first.status).toBe(0);
@@ -85,12 +132,31 @@ cp "$EDGE_EVER_TEST_COMPOSE_SOURCE" "$output"
expect(firstEnvironment).toContain("EDGE_EVER_VERSION='latest'");
expect(firstEnvironment).toContain("EDGE_EVER_PORT='18789'");
expect(firstEnvironment).toMatch(/EDGE_EVER_AUTH_PASSWORD='[a-f0-9]{32}'/);
+ const generatedPassword = firstEnvironment.match(
+ /EDGE_EVER_AUTH_PASSWORD='([a-f0-9]{32})'/,
+ )?.[1];
+ if (!generatedPassword) {
+ throw new Error("installer did not generate a password");
+ }
+ expect(first.stderr).toContain("[STEP 1/6] Validate environment");
+ expect(first.stderr).toContain("[STEP 6/6] Wait for health check");
+ expect(first.stderr).toContain("[SUCCESS] EdgeEver is ready");
+ expect(first.stderr).toContain("Host OS:");
+ expect(first.stderr).toContain("Kernel:");
+ expect(first.stderr).toContain("Architecture:");
+ expect(first.stderr).toContain("Docker Engine: 27.5.1");
+ expect(first.stderr).toContain("Docker Compose: 2.32.4");
+ expect(first.stderr).toContain(
+ "EdgeEver target: ccr.ccs.tencentyun.com/edgeever/edgeever:latest",
+ );
+ expect(first.stderr).toContain(
+ "Running image: ccr.ccs.tencentyun.com/edgeever/edgeever:latest",
+ );
+ expect(first.stderr).not.toContain(generatedPassword);
+ expect(first.stdout).toContain(`Password: ${generatedPassword}`);
+ expect(first.stdout).toContain("docker compose logs --tail 200 -f edgeever");
- const second = spawnSync("bash", [installerPath], {
- env: environment,
- encoding: "utf8",
- stdio: ["ignore", "ignore", "pipe"],
- });
+ const second = runInstaller([], environment);
if (second.status !== 0) {
throw new Error(
`installer rerun failed (exit=${second.status}, signal=${second.signal}):\n${second.stdout}\n${second.stderr}`,
@@ -114,4 +180,72 @@ cp "$EDGE_EVER_TEST_COMPOSE_SOURCE" "$output"
await rm(fixture, { recursive: true, force: true });
}
});
+
+ test("prints actionable diagnostics without exposing the password", async () => {
+ const fixture = await mkdtemp(resolve(tmpdir(), "edgeever-installer-failure-"));
+ const fakeBin = resolve(fixture, "bin");
+ const installDirectory = resolve(fixture, "edgeever");
+ const fakeDocker = resolve(fakeBin, "docker");
+ const fakeCurl = resolve(fakeBin, "curl");
+ const secret = "installer-secret-must-stay-hidden";
+
+ try {
+ await mkdir(fakeBin, { recursive: true });
+ await writeFile(
+ fakeDocker,
+ `#!/usr/bin/env bash
+set -eu
+if [[ "$*" == *" pull" ]]; then
+ printf 'mock pull failure\n' >&2
+ exit 42
+elif [[ "$*" == *" ps -a" ]]; then
+ printf 'mock container status\n'
+elif [[ "$*" == *" logs --tail 80 edgeever" ]]; then
+ printf 'mock recent logs\n'
+fi
+`,
+ );
+ await writeFile(
+ fakeCurl,
+ `#!/usr/bin/env bash
+set -eu
+while [[ $# -gt 0 ]]; do
+ if [[ "$1" == "--output" ]]; then
+ cp "$EDGE_EVER_TEST_COMPOSE_SOURCE" "$2"
+ exit 0
+ fi
+ shift
+done
+exit 1
+`,
+ );
+ await chmod(fakeDocker, 0o755);
+ await chmod(fakeCurl, 0o755);
+
+ const result = runInstaller(
+ [],
+ {
+ ...process.env,
+ PATH: `${fakeBin}:${process.env.PATH}`,
+ EDGE_EVER_AUTH_PASSWORD: secret,
+ EDGE_EVER_INSTALL_DIR: installDirectory,
+ EDGE_EVER_TEST_COMPOSE_SOURCE: composePath,
+ },
+ );
+
+ expect(result.status).toBe(42);
+ expect(result.stderr).toContain("A command failed (exit code: 42");
+ expect(result.stderr).toContain("Stage: Pull image and start container");
+ expect(result.stderr).toContain("Container status:");
+ expect(result.stderr).toContain("mock container status");
+ expect(result.stderr).toContain("Recent container logs:");
+ expect(result.stderr).toContain("mock recent logs");
+ expect(result.stderr).toContain("Troubleshooting commands:");
+ expect(result.stderr).toContain("docs/deploy-docker.md");
+ expect(result.stderr).not.toContain(secret);
+ expect(result.stdout).not.toContain(secret);
+ } finally {
+ await rm(fixture, { recursive: true, force: true });
+ }
+ });
});