Skip to content

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

feat: Introduce `nekoagent` CLI for agent instance management and update the installer to utilize it.

luolei2bad29df3071
diff --git a/apps/agent/README.md b/apps/agent/README.md
index cdfce59..5d267e1 100644
--- a/apps/agent/README.md
+++ b/apps/agent/README.md
@@ -53,6 +53,15 @@ curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/
sh
```
+Installer also provides `nekoagent` manager for friendly operations:
+
+```bash
+nekoagent status backend-1
+nekoagent logs backend-1
+nekoagent restart backend-1
+nekoagent update backend-1 agent-v1.3.2
+```
+
Pin release version (recommended for production):
```bash
diff --git a/apps/agent/install.sh b/apps/agent/install.sh
old mode 100644
new mode 100755
index 4751479..a317156
--- a/apps/agent/install.sh
+++ b/apps/agent/install.sh
@@ -81,25 +81,23 @@ 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_INSTALL_DIR="${NEKO_INSTALL_DIR:-$HOME/.local/bin}"
NEKO_LOG="${NEKO_LOG:-true}"
NEKO_AUTO_START="${NEKO_AUTO_START:-true}"
-NEKO_LOG_FILE="${NEKO_LOG_FILE:-$HOME/.cache/neko-agent-${NEKO_BACKEND_ID}.log}"
+NEKO_INSTANCE_NAME="${NEKO_INSTANCE_NAME:-backend-${NEKO_BACKEND_ID}}"
os="$(normalize_os)"
arch="$(normalize_arch)"
if [ "$NEKO_AGENT_VERSION" = "latest" ]; then
release_path="releases/latest/download"
-else
- release_path="releases/download/${NEKO_AGENT_VERSION}"
-fi
-
-if [ "$NEKO_AGENT_VERSION" = "latest" ]; then
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
@@ -114,12 +112,24 @@ 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 [ "$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"
@@ -163,38 +173,38 @@ 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"
+
if ! echo ":$PATH:" | grep -q ":$NEKO_INSTALL_DIR:"; then
echo "[neko-agent] warning: $NEKO_INSTALL_DIR is not in PATH"
fi
-set -- "$install_target" \
- --server-url "$NEKO_SERVER" \
- --backend-id "$NEKO_BACKEND_ID" \
- --backend-token "$NEKO_BACKEND_TOKEN" \
- --gateway-type "$NEKO_GATEWAY_TYPE" \
- --gateway-url "$NEKO_GATEWAY_URL" \
- --log="$NEKO_LOG"
-
-if [ -n "$NEKO_GATEWAY_TOKEN" ]; then
- set -- "$@" --gateway-token "$NEKO_GATEWAY_TOKEN"
-fi
+"$cli_target" init "$NEKO_INSTANCE_NAME" \
+ "NEKO_SERVER=$NEKO_SERVER" \
+ "NEKO_BACKEND_ID=$NEKO_BACKEND_ID" \
+ "NEKO_BACKEND_TOKEN=$NEKO_BACKEND_TOKEN" \
+ "NEKO_GATEWAY_TYPE=$NEKO_GATEWAY_TYPE" \
+ "NEKO_GATEWAY_URL=$NEKO_GATEWAY_URL" \
+ "NEKO_GATEWAY_TOKEN=$NEKO_GATEWAY_TOKEN" \
+ "NEKO_LOG=$NEKO_LOG"
echo "[neko-agent] installed to: $install_target"
-echo "[neko-agent] run command:"
-cat <<EOF
-$install_target \\
- --server-url "$NEKO_SERVER" \\
- --backend-id "$NEKO_BACKEND_ID" \\
- --backend-token "$NEKO_BACKEND_TOKEN" \\
- --gateway-type "$NEKO_GATEWAY_TYPE" \\
- --gateway-url "$NEKO_GATEWAY_URL" \\
- --log="$NEKO_LOG"$(if [ -n "$NEKO_GATEWAY_TOKEN" ]; then printf " \\\n+ --gateway-token \"$NEKO_GATEWAY_TOKEN\""; fi)
-EOF
+echo "[neko-agent] management cli: $cli_target"
+echo "[neko-agent] configured instance: $NEKO_INSTANCE_NAME"
+echo "[neko-agent] common commands:"
+echo " $cli_target start $NEKO_INSTANCE_NAME"
+echo " $cli_target stop $NEKO_INSTANCE_NAME"
+echo " $cli_target status $NEKO_INSTANCE_NAME"
+echo " $cli_target logs $NEKO_INSTANCE_NAME"
+echo " $cli_target update $NEKO_INSTANCE_NAME [agent-vX.Y.Z]"
if [ "$NEKO_AUTO_START" = "true" ]; then
- mkdir -p "$(dirname "$NEKO_LOG_FILE")"
- nohup "$@" >"$NEKO_LOG_FILE" 2>&1 &
- echo "[neko-agent] started in background, pid=$!, log=$NEKO_LOG_FILE"
+ "$cli_target" start "$NEKO_INSTANCE_NAME"
else
echo "[neko-agent] auto-start disabled (NEKO_AUTO_START=false)"
fi
diff --git a/apps/agent/neko-agent b/apps/agent/neko-agent
new file mode 100755
index 0000000..3abad61
Binary files /dev/null and b/apps/agent/neko-agent differ
diff --git a/apps/agent/nekoagent b/apps/agent/nekoagent
new file mode 100755
index 0000000..b4b5b98
--- /dev/null
+++ b/apps/agent/nekoagent
@@ -0,0 +1,337 @@
+#!/usr/bin/env sh
+set -eu
+
+PROG="nekoagent"
+INSTALL_DIR_DEFAULT="${HOME}/.local/bin"
+INSTALL_DIR="${NEKO_INSTALL_DIR:-$INSTALL_DIR_DEFAULT}"
+AGENT_BIN="${NEKO_AGENT_BIN:-$INSTALL_DIR/neko-agent}"
+CONFIG_DIR="${NEKO_AGENT_CONFIG_DIR:-/etc/neko-agent}"
+STATE_DIR="${NEKO_AGENT_STATE_DIR:-/var/run/neko-agent}"
+
+log() {
+ printf '[%s] %s\n' "$PROG" "$1"
+}
+
+err() {
+ printf '[%s] error: %s\n' "$PROG" "$1" >&2
+}
+
+ensure_dirs() {
+ mkdir -p "$CONFIG_DIR" "$STATE_DIR"
+}
+
+config_file() {
+ name="$1"
+ printf '%s/%s.env\n' "$CONFIG_DIR" "$name"
+}
+
+pid_file() {
+ name="$1"
+ printf '%s/%s.pid\n' "$STATE_DIR" "$name"
+}
+
+log_file() {
+ name="$1"
+ printf '%s/%s.log\n' "$STATE_DIR" "$name"
+}
+
+is_running() {
+ name="$1"
+ pf="$(pid_file "$name")"
+ if [ ! -f "$pf" ]; then
+ return 1
+ fi
+ pid="$(cat "$pf" 2>/dev/null || true)"
+ if [ -z "$pid" ]; then
+ return 1
+ fi
+ kill -0 "$pid" >/dev/null 2>&1
+}
+
+usage() {
+ cat <<EOF
+Usage:
+ $PROG init <name> [KEY=VALUE ...] Create/overwrite config file
+ $PROG start <name> Start agent instance
+ $PROG stop <name> Stop agent instance
+ $PROG restart <name> Restart agent instance
+ $PROG status <name> Show instance status
+ $PROG logs <name> Tail logs
+ $PROG list List configured instances
+ $PROG update <name> [version] Update agent binary and restart instance
+
+Config and runtime paths:
+ CONFIG_DIR=$CONFIG_DIR
+ STATE_DIR=$STATE_DIR
+ AGENT_BIN=$AGENT_BIN
+
+Required config keys:
+ NEKO_SERVER, NEKO_BACKEND_ID, NEKO_BACKEND_TOKEN, NEKO_GATEWAY_TYPE, NEKO_GATEWAY_URL
+Optional keys:
+ NEKO_GATEWAY_TOKEN, NEKO_LOG, NEKO_AGENT_ID, NEKO_REPORT_INTERVAL,
+ NEKO_HEARTBEAT_INTERVAL, NEKO_GATEWAY_POLL_INTERVAL, NEKO_REQUEST_TIMEOUT,
+ NEKO_REPORT_BATCH_SIZE, NEKO_MAX_PENDING_UPDATES, NEKO_STALE_FLOW_TIMEOUT
+EOF
+}
+
+require_config_key() {
+ key="$1"
+ eval "val=\${$key:-}"
+ if [ -z "$val" ]; then
+ err "missing required key in config: $key"
+ exit 1
+ fi
+}
+
+load_config() {
+ name="$1"
+ cf="$(config_file "$name")"
+ if [ ! -f "$cf" ]; then
+ err "config not found: $cf"
+ exit 1
+ fi
+ # shellcheck disable=SC1090
+ . "$cf"
+ require_config_key "NEKO_SERVER"
+ require_config_key "NEKO_BACKEND_ID"
+ require_config_key "NEKO_BACKEND_TOKEN"
+ require_config_key "NEKO_GATEWAY_TYPE"
+ require_config_key "NEKO_GATEWAY_URL"
+}
+
+build_agent_args() {
+ set -- \
+ --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 [ -n "${NEKO_AGENT_ID:-}" ]; then
+ set -- "$@" --agent-id "$NEKO_AGENT_ID"
+ fi
+ if [ -n "${NEKO_REPORT_INTERVAL:-}" ]; then
+ set -- "$@" --report-interval "$NEKO_REPORT_INTERVAL"
+ fi
+ if [ -n "${NEKO_HEARTBEAT_INTERVAL:-}" ]; then
+ set -- "$@" --heartbeat-interval "$NEKO_HEARTBEAT_INTERVAL"
+ fi
+ if [ -n "${NEKO_GATEWAY_POLL_INTERVAL:-}" ]; then
+ set -- "$@" --gateway-poll-interval "$NEKO_GATEWAY_POLL_INTERVAL"
+ fi
+ if [ -n "${NEKO_REQUEST_TIMEOUT:-}" ]; then
+ set -- "$@" --request-timeout "$NEKO_REQUEST_TIMEOUT"
+ fi
+ if [ -n "${NEKO_REPORT_BATCH_SIZE:-}" ]; then
+ set -- "$@" --report-batch-size "$NEKO_REPORT_BATCH_SIZE"
+ fi
+ if [ -n "${NEKO_MAX_PENDING_UPDATES:-}" ]; then
+ set -- "$@" --max-pending-updates "$NEKO_MAX_PENDING_UPDATES"
+ fi
+ if [ -n "${NEKO_STALE_FLOW_TIMEOUT:-}" ]; then
+ set -- "$@" --stale-flow-timeout "$NEKO_STALE_FLOW_TIMEOUT"
+ fi
+
+ log_enabled="${NEKO_LOG:-true}"
+ set -- "$@" --log="$log_enabled"
+
+ printf '%s\n' "$*"
+}
+
+cmd_init() {
+ name="$1"
+ shift
+ ensure_dirs
+ cf="$(config_file "$name")"
+ umask 077
+ : > "$cf"
+ for kv in "$@"; do
+ case "$kv" in
+ *=*) printf '%s\n' "$kv" >> "$cf" ;;
+ *)
+ err "invalid key=value pair: $kv"
+ exit 1
+ ;;
+ esac
+ done
+ log "config written: $cf"
+}
+
+cmd_start() {
+ name="$1"
+ ensure_dirs
+ if [ ! -x "$AGENT_BIN" ]; then
+ err "agent binary not found/executable: $AGENT_BIN"
+ exit 1
+ fi
+ if is_running "$name"; then
+ log "instance '$name' already running (pid $(cat "$(pid_file "$name")"))"
+ exit 0
+ fi
+
+ load_config "$name"
+ args="$(build_agent_args)"
+ lf="$(log_file "$name")"
+ pf="$(pid_file "$name")"
+
+ nohup "$AGENT_BIN" $args >> "$lf" 2>&1 &
+ pid=$!
+ printf '%s\n' "$pid" > "$pf"
+ log "instance '$name' started, pid=$pid, log=$lf"
+}
+
+cmd_stop() {
+ name="$1"
+ pf="$(pid_file "$name")"
+ if ! is_running "$name"; then
+ rm -f "$pf"
+ log "instance '$name' is not running"
+ exit 0
+ fi
+ pid="$(cat "$pf")"
+ kill "$pid" >/dev/null 2>&1 || true
+ sleep 1
+ if kill -0 "$pid" >/dev/null 2>&1; then
+ kill -9 "$pid" >/dev/null 2>&1 || true
+ fi
+ rm -f "$pf"
+ log "instance '$name' stopped"
+}
+
+cmd_status() {
+ name="$1"
+ if is_running "$name"; then
+ log "instance '$name' is running (pid $(cat "$(pid_file "$name")"))"
+ exit 0
+ fi
+ log "instance '$name' is stopped"
+ exit 1
+}
+
+cmd_logs() {
+ name="$1"
+ lf="$(log_file "$name")"
+ if [ ! -f "$lf" ]; then
+ err "log file not found: $lf"
+ exit 1
+ fi
+ tail -f "$lf"
+}
+
+cmd_list() {
+ ensure_dirs
+ found=false
+ for f in "$CONFIG_DIR"/*.env; do
+ if [ ! -e "$f" ]; then
+ continue
+ fi
+ found=true
+ name="$(basename "$f" .env)"
+ if is_running "$name"; then
+ status="running"
+ else
+ status="stopped"
+ fi
+ printf '%s\t%s\n' "$name" "$status"
+ done
+ if [ "$found" = false ]; then
+ log "no instances configured"
+ fi
+}
+
+cmd_update() {
+ name="$1"
+ version="${2:-latest}"
+ load_config "$name"
+ was_running=false
+ if is_running "$name"; then
+ was_running=true
+ cmd_stop "$name"
+ fi
+
+ install_script_url="https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh"
+ tmp_script="$(mktemp)"
+ trap 'rm -f "$tmp_script"' EXIT INT TERM
+
+ if command -v curl >/dev/null 2>&1; then
+ curl -fsSL "$install_script_url" -o "$tmp_script"
+ elif command -v wget >/dev/null 2>&1; then
+ wget -qO "$tmp_script" "$install_script_url"
+ else
+ err "curl or wget is required"
+ exit 1
+ fi
+
+ env \
+ NEKO_SERVER="$NEKO_SERVER" \
+ NEKO_BACKEND_ID="$NEKO_BACKEND_ID" \
+ NEKO_BACKEND_TOKEN="$NEKO_BACKEND_TOKEN" \
+ NEKO_GATEWAY_TYPE="$NEKO_GATEWAY_TYPE" \
+ NEKO_GATEWAY_URL="$NEKO_GATEWAY_URL" \
+ NEKO_GATEWAY_TOKEN="${NEKO_GATEWAY_TOKEN:-}" \
+ NEKO_AGENT_VERSION="$version" \
+ NEKO_INSTALL_DIR="$INSTALL_DIR" \
+ NEKO_AUTO_START="false" \
+ sh "$tmp_script"
+
+ if [ "$was_running" = true ]; then
+ cmd_start "$name"
+ fi
+ log "instance '$name' updated to $version"
+}
+
+main() {
+ if [ "$#" -lt 1 ]; then
+ usage
+ exit 1
+ fi
+
+ cmd="$1"
+ shift
+
+ case "$cmd" in
+ init)
+ if [ "$#" -lt 2 ]; then
+ usage
+ exit 1
+ fi
+ cmd_init "$@"
+ ;;
+ start|stop|restart|status|logs)
+ if [ "$#" -ne 1 ]; then
+ usage
+ exit 1
+ fi
+ case "$cmd" in
+ start) cmd_start "$1" ;;
+ stop) cmd_stop "$1" ;;
+ restart) cmd_stop "$1" || true; cmd_start "$1" ;;
+ status) cmd_status "$1" ;;
+ logs) cmd_logs "$1" ;;
+ esac
+ ;;
+ update)
+ if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
+ usage
+ exit 1
+ fi
+ cmd_update "$@"
+ ;;
+ list)
+ cmd_list
+ ;;
+ help|-h|--help)
+ usage
+ ;;
+ *)
+ err "unknown command: $cmd"
+ usage
+ exit 1
+ ;;
+ esac
+}
+
+main "$@"
diff --git a/docs/agent/install.md b/docs/agent/install.md
index 4f6728c..5aa96ad 100644
--- a/docs/agent/install.md
+++ b/docs/agent/install.md
@@ -34,6 +34,16 @@ Optional env:
- `NEKO_LOG_FILE`: runtime log file path
- `NEKO_PACKAGE_URL`: custom package URL override
- `NEKO_CHECKSUMS_URL`: custom checksums URL override
+- `NEKO_INSTANCE_NAME`: instance name for `nekoagent` manager (default `backend-<id>`)
+
+After install, manage agent with:
+
+```bash
+nekoagent status <instance>
+nekoagent logs <instance>
+nekoagent restart <instance>
+nekoagent update <instance> agent-vX.Y.Z
+```
## Manual install