Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

15.4 KB
Raw Blame
#!/usr/bin/env sh
set -eu

# Neko Agent Install Script
# Features:
#   - Detects existing nekoagent installation
#   - Uses local nekoagent if available
#   - Supports adding multiple backend instances

VERSION="0.2.0"

require_env() {
	key="$1"
	eval "val=\${$key:-}"
	if [ -z "$val" ]; then
		echo "[neko-agent] error: env $key is required" >&2
		exit 1
	fi
}

show_intro() {
	cat <<'EOF'
╔════════════════════════════════════════════════════════════╗
║                    Neko Master Agent                      ║
╚════════════════════════════════════════════════════════════╝

Neko Master is a centralized traffic analytics panel.
Agent runs near your local gateway and reports data securely to the panel.

Project:
  https://github.com/foru17/neko-master

Agent docs:
  https://github.com/foru17/neko-master/tree/main/docs/agent

EOF
}

detect_existing_install() {
	# Check for nekoagent in common locations
	if command -v nekoagent >/dev/null 2>&1; then
		echo "$(command -v nekoagent)"
		return 0
	fi

	# Check default install locations
	for path in "$HOME/.local/bin/nekoagent" "/usr/local/bin/nekoagent"; do
		if [ -x "$path" ]; then
			echo "$path"
			return 0
		fi
	done

	# Not found
	return 1
}

wget_with_retries() (
	# BusyBox wget may not support --tries; keep its fallback bounded too.
	if wget --help 2>&1 | grep -q -- --tries; then
		wget --timeout=120 --tries=3 "$@"
		return $?
	fi
	attempt=0
	while [ "$attempt" -lt 3 ]; do
		if wget --timeout=120 "$@"; then
			return 0
		else
			download_status=$?
		fi
		attempt=$((attempt + 1))
	done
	return "$download_status"
)

download_file() {
	url="$1"
	output="$2"
	# Propagate the downloader's exit status (a plain `return 0` would mask
	# failures when callers invoke this inside a condition under `set -e`).
	if command -v curl >/dev/null 2>&1; then
		curl -fsSL --connect-timeout 10 --max-time 120 --retry 3 --retry-delay 2 "$url" -o "$output"
		return $?
	fi
	if command -v wget >/dev/null 2>&1; then
		wget_with_retries -qO "$output" "$url"
		return $?
	fi
	echo "[neko-agent] error: curl or wget is required" >&2
	exit 1
}

normalize_os() {
	raw="$(uname -s | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz')"
	case "$raw" in
	linux) echo "linux" ;;
	darwin) echo "darwin" ;;
	*)
		echo "[neko-agent] error: unsupported OS: $raw" >&2
		exit 1
		;;
	esac
}

normalize_arch() {
	raw="$(uname -m | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz')"
	case "$raw" in
	x86_64 | amd64) echo "amd64" ;;
	aarch64 | arm64) echo "arm64" ;;
	armv7l | armv7 | armhf) echo "armv7" ;;
	mips) echo "mips" ;;
	mipsle) echo "mipsle" ;;
	*)
		echo "[neko-agent] error: unsupported architecture: $raw" >&2
		echo "[neko-agent] hint: set NEKO_PACKAGE_URL manually if your target is exotic" >&2
		exit 1
		;;
	esac
}

# Query GitHub releases API for the latest agent tag (e.g. "agent-v0.2.0").
# Reports HTTP/download errors on stderr and returns non-zero on failure.
#
# The repo publishes BOTH main-app (v*) and agent (agent-v*) releases into the
# same namespace, and either may be marked "latest". So we must NOT use the
# releases/latest endpoint — it can resolve to a main-app release that carries
# no agent binaries. Instead list recent releases and pick the newest agent-v*.
get_latest_remote_tag() (
	repo="${1:-foru17/neko-master}"
	api_url="https://api.github.com/repos/${repo}/releases?per_page=100"
	token="${GITHUB_TOKEN:-${GITHUB_PAT:-}}"
	# Isolate temporary files, credentials and traps from the install/upgrade flow.
	umask 077
	api_tmp_dir="$(mktemp -d)" || return 1
	trap 'rm -rf "$api_tmp_dir"' 0
	trap 'exit 1' 1 2 15
	request_status=0
	if command -v curl >/dev/null 2>&1; then
		set -- -fsSL --connect-timeout 10 --max-time 120 --retry 3 --retry-delay 2
		if [ -n "$token" ]; then
			set -- "$@" -H "Authorization: Bearer $token"
		fi
		http_code="$(curl "$@" -o "$api_tmp_dir/body" -w '%{http_code}' "$api_url" 2>/dev/null)" || request_status=$?
	elif command -v wget >/dev/null 2>&1; then
		set -- -S -O "$api_tmp_dir/body"
		if [ -n "$token" ]; then
			set -- "$@" --header="Authorization: Bearer $token"
		fi
		wget_with_retries "$@" "$api_url" 2>"$api_tmp_dir/headers" || request_status=$?
		http_code="$(awk '$1 ~ /^HTTP\// && $2 ~ /^[0-9][0-9][0-9]$/ {code=$2} END {print code}' "$api_tmp_dir/headers")"
	else
		echo "[neko-agent] error: curl or wget is required" >&2
		return 1
	fi

	case "$http_code" in
		401) api_error="GitHub token rejected (401)" ;;
		403|429) api_error="GitHub API rate limit or forbidden (HTTP $http_code); set GITHUB_TOKEN" ;;
		2??) api_error="" ;;
		*) api_error="GitHub API request failed (HTTP ${http_code:-unknown})" ;;
	esac
	if [ -n "$api_error" ]; then
		echo "[neko-agent] error: $api_error" >&2
		return 1
	fi
	if [ "$request_status" -ne 0 ]; then
		echo "[neko-agent] error: GitHub API download failed (HTTP $http_code; downloader exit $request_status)" >&2
		return 1
	fi
	tag="$(awk -F'"' '/"tag_name"/{print $4}' "$api_tmp_dir/body" | grep '^agent-v' | head -1)"
	if [ -z "$tag" ]; then
		echo "[neko-agent] error: no agent-v* release found in GitHub API response" >&2
		return 1
	fi
	printf '%s\n' "$tag"
)

compute_sha256() {
	file="$1"
	if command -v sha256sum >/dev/null 2>&1; then
		sha256sum "$file" | awk '{print $1}'
		return 0
	fi
	if command -v shasum >/dev/null 2>&1; then
		shasum -a 256 "$file" | awk '{print $1}'
		return 0
	fi
	if command -v openssl >/dev/null 2>&1; then
		openssl dgst -sha256 "$file" | awk '{print $2}'
		return 0
	fi
	echo ""
}

# Use local nekoagent to add instance
use_local_agent() {
	nekoagent_path="$1"
	instance_name="${NEKO_INSTANCE_NAME:-backend-${NEKO_BACKEND_ID}}"

	echo "[neko-agent] detected existing installation: $nekoagent_path"
	echo "[neko-agent] using local nekoagent to add instance..."

	# Build add command
	set -- \
		"$nekoagent_path" add "$instance_name" \
		--server-url "$NEKO_SERVER" \
		--backend-id "$NEKO_BACKEND_ID" \
		--backend-token "$NEKO_BACKEND_TOKEN" \
		--gateway-type "$NEKO_GATEWAY_TYPE" \
		--gateway-url "$NEKO_GATEWAY_URL"

	if [ -n "${NEKO_GATEWAY_TOKEN:-}" ]; then
		set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
	fi

	if [ "${NEKO_AUTO_START:-true}" != "true" ]; then
		set -- "$@" --no-start
	fi

	# Execute
	"$@"

	if [ "${NEKO_AUTO_START:-true}" = "true" ]; then
		if "$nekoagent_path" enable-autostart "$instance_name"; then
			echo "[neko-agent] boot autostart enabled for: $instance_name"
		else
			echo "[neko-agent] warning: failed to enable boot autostart (instance still configured)"
			echo "[neko-agent] hint: run manually: $nekoagent_path enable-autostart $instance_name"
		fi
	fi
}

show_plan() {
	token_mode="not set"
	if [ -n "${NEKO_GATEWAY_TOKEN:-}" ]; then
		token_mode="provided"
	fi

	cat <<EOF
[neko-agent] install plan:
  target:            ${os}/${arch}
  version:           ${NEKO_AGENT_VERSION}
  backend id:        ${NEKO_BACKEND_ID}
  instance:          ${NEKO_INSTANCE_NAME}
  gateway type:      ${NEKO_GATEWAY_TYPE}
  gateway url:       ${NEKO_GATEWAY_URL}
  gateway token:     ${token_mode}
  install dir:       ${NEKO_INSTALL_DIR}
  auto start:        ${NEKO_AUTO_START}
EOF
}

# Main installation flow
main() {
	require_env "NEKO_SERVER"
	require_env "NEKO_BACKEND_ID"
	require_env "NEKO_BACKEND_TOKEN"
	require_env "NEKO_GATEWAY_URL"

	show_intro

	# Environment defaults
	NEKO_GATEWAY_TYPE="${NEKO_GATEWAY_TYPE:-clash}"
	NEKO_GATEWAY_TOKEN="${NEKO_GATEWAY_TOKEN:-}"
	NEKO_AGENT_REPO="${NEKO_AGENT_REPO:-foru17/neko-master}"
	NEKO_AGENT_VERSION="${NEKO_AGENT_VERSION:-latest}"
	NEKO_PACKAGE_URL="${NEKO_PACKAGE_URL:-}"
	NEKO_CHECKSUMS_URL="${NEKO_CHECKSUMS_URL:-}"
	NEKO_CLI_URL="${NEKO_CLI_URL:-}"
	# NEKO_AGENT_REF: override the git branch/ref used to download the nekoagent manager script.
	# Useful for testing unreleased branches (e.g. NEKO_AGENT_REF=refactor/clickhouse).
	# When unset: uses "main" for latest, or the version tag for pinned versions.
	NEKO_AGENT_REF="${NEKO_AGENT_REF:-}"
	NEKO_INSTALL_DIR="${NEKO_INSTALL_DIR:-$HOME/.local/bin}"
	NEKO_BIN_LINK_MODE="${NEKO_BIN_LINK_MODE:-auto}"
	NEKO_LINK_DIR="${NEKO_LINK_DIR:-/usr/local/bin}"
	NEKO_LOG="${NEKO_LOG:-true}"
	NEKO_AUTO_START="${NEKO_AUTO_START:-true}"
	NEKO_INSTANCE_NAME="${NEKO_INSTANCE_NAME:-backend-${NEKO_BACKEND_ID}}"

	os="$(normalize_os)"
	arch="$(normalize_arch)"

	# Check if nekoagent is already installed
	existing_agent="$(detect_existing_install || true)"

	# If already installed, check whether the binary is up-to-date before deciding
	if [ -n "$existing_agent" ] && [ "${NEKO_FORCE_INSTALL:-false}" != "true" ]; then
		# Locate the neko-agent binary (same dir as nekoagent, or /usr/local/bin fallback)
		existing_bin="$(dirname "$existing_agent")/neko-agent"
		[ -x "$existing_bin" ] || existing_bin="/usr/local/bin/neko-agent"

		local_version=""
		if [ -x "$existing_bin" ]; then
			local_version="$("$existing_bin" --version 2>/dev/null | head -1 || true)"
		fi

		# Determine target plain version (strip "agent-v" prefix)
		if [ "$NEKO_AGENT_VERSION" = "latest" ]; then
			resolved_tag="$(get_latest_remote_tag "$NEKO_AGENT_REPO")" || resolved_tag=""
			remote_tag="$resolved_tag"
			target_version="${remote_tag#agent-v}"
		else
			target_version="${NEKO_AGENT_VERSION#agent-v}"
			target_version="${target_version#v}"
		fi

		# If versions match, skip download and just add the instance
		if [ -n "$local_version" ] && [ -n "$target_version" ] && [ "$local_version" = "$target_version" ]; then
			echo "[neko-agent] binary already at $local_version, skipping download"
			use_local_agent "$existing_agent"
			exit 0
		fi

		if [ -n "$local_version" ]; then
			echo "[neko-agent] binary update: $local_version -> ${target_version:-latest}"
		else
			echo "[neko-agent] binary not found or version unknown, downloading..."
		fi
		# Fall through to full download/install, then re-use existing nekoagent to add instance
	fi

	# Full installation needed
	show_plan

	if [ "$NEKO_AGENT_VERSION" = "latest" ]; then
		# Resolve "latest" to a concrete agent-v* tag. releases/latest/download is
		# unsafe here: it points at whatever release GitHub marks latest, which may
		# be a main-app v* release with no agent binaries (→ 404).
		if [ -z "${resolved_tag:-}" ]; then
			resolved_tag="$(get_latest_remote_tag "$NEKO_AGENT_REPO")" || resolved_tag=""
		fi
		if [ -z "$resolved_tag" ]; then
			echo "[neko-agent] error: could not determine latest agent version from GitHub API" >&2
			echo "[neko-agent] hint: check network access or pin a version: NEKO_AGENT_VERSION=agent-vX.Y.Z" >&2
			exit 1
		fi
		release_path="releases/download/${resolved_tag}"
		asset="neko-agent_${os}_${arch}.tar.gz"
	else
		release_path="releases/download/${NEKO_AGENT_VERSION}"
		asset="neko-agent_${NEKO_AGENT_VERSION}_${os}_${arch}.tar.gz"
	fi

	checksums_asset="checksums.txt"

	if [ -n "$NEKO_PACKAGE_URL" ]; then
		package_url="$NEKO_PACKAGE_URL"
	else
		package_url="https://github.com/${NEKO_AGENT_REPO}/${release_path}/${asset}"
	fi

	if [ -n "$NEKO_CHECKSUMS_URL" ]; then
		checksums_url="$NEKO_CHECKSUMS_URL"
	else
		checksums_url="https://github.com/${NEKO_AGENT_REPO}/${release_path}/${checksums_asset}"
	fi

	if [ -n "$NEKO_CLI_URL" ]; then
		cli_url="$NEKO_CLI_URL"
	else
		if [ -n "$NEKO_AGENT_REF" ]; then
			cli_ref="$NEKO_AGENT_REF"
		elif [ "$NEKO_AGENT_VERSION" = "latest" ]; then
			cli_ref="main"
		else
			cli_ref="$NEKO_AGENT_VERSION"
		fi
		cli_url="https://raw.githubusercontent.com/${NEKO_AGENT_REPO}/${cli_ref}/apps/agent/nekoagent"
	fi

	tmp_dir="${TMPDIR:-/tmp}/neko-agent.$$"
	mkdir -p "$tmp_dir"
	trap 'rm -rf "$tmp_dir"' EXIT INT TERM

	archive_path="$tmp_dir/neko-agent.tar.gz"
	checksums_path="$tmp_dir/checksums.txt"
	cli_path="$tmp_dir/nekoagent"

	echo "[neko-agent] downloading package: $package_url"
	download_file "$package_url" "$archive_path"

	if [ -z "$NEKO_PACKAGE_URL" ]; then
		echo "[neko-agent] downloading checksums: $checksums_url"
		download_file "$checksums_url" "$checksums_path"

		expected_hash="$(awk '$2 == "'"$asset"'" {print $1}' "$checksums_path" | head -n 1)"
		if [ -z "$expected_hash" ]; then
			echo "[neko-agent] error: cannot find checksum for $asset" >&2
			exit 1
		fi

		actual_hash="$(compute_sha256 "$archive_path")"
		if [ -z "$actual_hash" ]; then
			echo "[neko-agent] error: missing sha256 tooling (sha256sum/shasum/openssl)" >&2
			exit 1
		fi

		if [ "$expected_hash" != "$actual_hash" ]; then
			echo "[neko-agent] error: checksum mismatch for $asset" >&2
			echo "[neko-agent] expected: $expected_hash" >&2
			echo "[neko-agent] actual:   $actual_hash" >&2
			exit 1
		fi
	fi

	mkdir -p "$tmp_dir/extract"
	tar -xzf "$archive_path" -C "$tmp_dir/extract"

	binary_source="$tmp_dir/extract/neko-agent"
	if [ ! -f "$binary_source" ]; then
		echo "[neko-agent] error: extracted archive does not contain neko-agent" >&2
		exit 1
	fi

	chmod +x "$binary_source"
	mkdir -p "$NEKO_INSTALL_DIR"
	install_target="$NEKO_INSTALL_DIR/neko-agent"
	mv "$binary_source" "$install_target"
	chmod +x "$install_target"

	echo "[neko-agent] downloading manager cli: $cli_url"
	download_file "$cli_url" "$cli_path"
	chmod +x "$cli_path"
	cli_target="$NEKO_INSTALL_DIR/nekoagent"
	mv "$cli_path" "$cli_target"
	chmod +x "$cli_target"

	linked_to_path="false"
	if [ "$NEKO_BIN_LINK_MODE" != "false" ]; then
		can_link="false"
		if [ "$NEKO_BIN_LINK_MODE" = "true" ]; then
			can_link="true"
		elif [ -d "$NEKO_LINK_DIR" ] && [ -w "$NEKO_LINK_DIR" ]; then
			can_link="true"
		fi

		if [ "$can_link" = "true" ]; then
			if mkdir -p "$NEKO_LINK_DIR" 2>/dev/null; then
				if ln -sf "$install_target" "$NEKO_LINK_DIR/neko-agent" 2>/dev/null &&
					ln -sf "$cli_target" "$NEKO_LINK_DIR/nekoagent" 2>/dev/null; then
					linked_to_path="true"
					echo "[neko-agent] linked binaries into: $NEKO_LINK_DIR"
				fi
			fi
		fi
	fi

	if [ "$linked_to_path" = "false" ] && ! echo ":$PATH:" | grep -q ":$NEKO_INSTALL_DIR:"; then
		echo "[neko-agent] warning: $NEKO_INSTALL_DIR is not in PATH"
		echo "[neko-agent] hint: use full path: $cli_target status $NEKO_INSTANCE_NAME"
		echo "[neko-agent] hint: add PATH in shell profile: export PATH=\"$NEKO_INSTALL_DIR:\$PATH\""
	fi

	# Use the newly installed nekoagent to add instance
	set -- add "$NEKO_INSTANCE_NAME" \
		--server-url "$NEKO_SERVER" \
		--backend-id "$NEKO_BACKEND_ID" \
		--backend-token "$NEKO_BACKEND_TOKEN" \
		--gateway-type "$NEKO_GATEWAY_TYPE" \
		--gateway-url "$NEKO_GATEWAY_URL"
	if [ -n "$NEKO_GATEWAY_TOKEN" ]; then
		set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
	fi
	if [ "$NEKO_AUTO_START" != "true" ]; then
		set -- "$@" --no-start
	fi
	"$cli_target" "$@"

	if [ "$NEKO_AUTO_START" = "true" ]; then
		if "$cli_target" enable-autostart "$NEKO_INSTANCE_NAME"; then
			echo "[neko-agent] boot autostart enabled for: $NEKO_INSTANCE_NAME"
		else
			echo "[neko-agent] warning: failed to enable boot autostart (instance still configured)"
			echo "[neko-agent] hint: run manually: $cli_target enable-autostart $NEKO_INSTANCE_NAME"
		fi
	fi

	echo "[neko-agent] installed to: $install_target"
	echo "[neko-agent] management cli: $cli_target"
	echo "[neko-agent] configured instance: $NEKO_INSTANCE_NAME"
	echo "[neko-agent] common commands:"
	echo "  nekoagent list"
	echo "  nekoagent start $NEKO_INSTANCE_NAME"
	echo "  nekoagent stop $NEKO_INSTANCE_NAME"
	echo "  nekoagent status $NEKO_INSTANCE_NAME"
	echo "  nekoagent logs $NEKO_INSTANCE_NAME"
	echo "  nekoagent upgrade"
	echo "  nekoagent remove $NEKO_INSTANCE_NAME"
}

main "$@"