Skip to content

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

feat: Implement agent autostart functionality using system service managers (systemd, launchd, OpenWrt, cron).

luolei34c5134cae2f
diff --git a/apps/agent/README.md b/apps/agent/README.md
index 7663262..953fb40 100644
--- a/apps/agent/README.md
+++ b/apps/agent/README.md
@@ -111,7 +111,7 @@ Quiet mode (no runtime logs):
Install script env (optional):
- `NEKO_GATEWAY_TOKEN`: gateway token
-- `NEKO_AUTO_START`: `true|false` (default `true`)
+- `NEKO_AUTO_START`: `true|false` (default `true`, starts now and registers boot autostart when supported)
- `NEKO_LOG`: `true|false` (default `true`)
- `NEKO_INSTALL_DIR`: install path (default `$HOME/.local/bin`)
- `NEKO_AGENT_VERSION`: release tag, default `latest` (for tagged version use `agent-vX.Y.Z`)
diff --git a/apps/agent/install.sh b/apps/agent/install.sh
index b887c49..1644e13 100755
--- a/apps/agent/install.sh
+++ b/apps/agent/install.sh
@@ -42,7 +42,7 @@ detect_existing_install() {
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
@@ -50,7 +50,7 @@ detect_existing_install() {
return 0
fi
done
-
+
# Not found
return 1
}
@@ -133,10 +133,10 @@ compute_sha256() {
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" \
@@ -145,17 +145,26 @@ use_local_agent() {
--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() {
@@ -383,6 +392,15 @@ main() {
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"
diff --git a/apps/agent/nekoagent b/apps/agent/nekoagent
index b11b450..6b50745 100755
--- a/apps/agent/nekoagent
+++ b/apps/agent/nekoagent
@@ -111,6 +111,319 @@ normalize_arch() {
esac
}
+detect_service_manager() {
+ os="$(normalize_os)"
+ if [ "$os" = "linux" ] && [ -f "/etc/openwrt_release" ] && [ -f "/etc/rc.common" ]; then
+ echo "openwrt"
+ return 0
+ fi
+
+ if [ "$os" = "linux" ] && command -v systemctl >/dev/null 2>&1 && [ -d "/etc/systemd/system" ]; then
+ echo "systemd"
+ return 0
+ fi
+
+ if [ "$os" = "darwin" ] && command -v launchctl >/dev/null 2>&1; then
+ echo "launchd"
+ return 0
+ fi
+
+ if command -v crontab >/dev/null 2>&1; then
+ echo "cron"
+ return 0
+ fi
+
+ echo "none"
+}
+
+service_name_for_instance() {
+ name="$1"
+ printf 'neko-agent-%s\n' "$name"
+}
+
+runner_file() {
+ name="$1"
+ printf '%s/%s.run.sh\n' "$CONFIG_DIR" "$name"
+}
+
+require_linux_root() {
+ manager="$1"
+ if [ "$manager" = "systemd" ] || [ "$manager" = "openwrt" ]; then
+ if [ "$(id -u)" -ne 0 ]; then
+ err "$manager autostart requires root privileges"
+ exit 1
+ fi
+ fi
+}
+
+generate_runner_script() {
+ name="$1"
+ rf="$(runner_file "$name")"
+ cf="$(config_file "$name")"
+ ensure_dirs
+
+ cat > "$rf" <<EOF
+#!/usr/bin/env sh
+set -eu
+
+AGENT_BIN='$AGENT_BIN'
+CONF='$cf'
+
+[ -f "\$CONF" ] || {
+ echo "[nekoagent] error: config not found: \$CONF" >&2
+ exit 1
+}
+
+. "\$CONF"
+
+: "\${NEKO_SERVER:?missing NEKO_SERVER}"
+: "\${NEKO_BACKEND_ID:?missing NEKO_BACKEND_ID}"
+: "\${NEKO_BACKEND_TOKEN:?missing NEKO_BACKEND_TOKEN}"
+: "\${NEKO_GATEWAY_TYPE:?missing NEKO_GATEWAY_TYPE}"
+: "\${NEKO_GATEWAY_URL:?missing NEKO_GATEWAY_URL}"
+
+set -- "\$AGENT_BIN" \
+ --server-url "\$NEKO_SERVER" \
+ --backend-id "\$NEKO_BACKEND_ID" \
+ --backend-token "\$NEKO_BACKEND_TOKEN" \
+ --gateway-type "\$NEKO_GATEWAY_TYPE" \
+ --gateway-url "\$NEKO_GATEWAY_URL"
+
+[ -n "\${NEKO_GATEWAY_TOKEN:-}" ] && set -- "\$@" --gateway-token "\$NEKO_GATEWAY_TOKEN"
+[ -n "\${NEKO_AGENT_ID:-}" ] && set -- "\$@" --agent-id "\$NEKO_AGENT_ID"
+[ -n "\${NEKO_REPORT_INTERVAL:-}" ] && set -- "\$@" --report-interval "\$NEKO_REPORT_INTERVAL"
+[ -n "\${NEKO_HEARTBEAT_INTERVAL:-}" ] && set -- "\$@" --heartbeat-interval "\$NEKO_HEARTBEAT_INTERVAL"
+[ -n "\${NEKO_GATEWAY_POLL_INTERVAL:-}" ] && set -- "\$@" --gateway-poll-interval "\$NEKO_GATEWAY_POLL_INTERVAL"
+[ -n "\${NEKO_REQUEST_TIMEOUT:-}" ] && set -- "\$@" --request-timeout "\$NEKO_REQUEST_TIMEOUT"
+[ -n "\${NEKO_REPORT_BATCH_SIZE:-}" ] && set -- "\$@" --report-batch-size "\$NEKO_REPORT_BATCH_SIZE"
+[ -n "\${NEKO_MAX_PENDING_UPDATES:-}" ] && set -- "\$@" --max-pending-updates "\$NEKO_MAX_PENDING_UPDATES"
+[ -n "\${NEKO_STALE_FLOW_TIMEOUT:-}" ] && set -- "\$@" --stale-flow-timeout "\$NEKO_STALE_FLOW_TIMEOUT"
+
+set -- "\$@" --log="\${NEKO_LOG:-true}"
+exec "\$@"
+EOF
+
+ chmod +x "$rf"
+ printf '%s\n' "$rf"
+}
+
+write_systemd_unit() {
+ name="$1"
+ runner="$2"
+ service="$(service_name_for_instance "$name")"
+ unit_path="/etc/systemd/system/${service}.service"
+ cat > "$unit_path" <<EOF
+[Unit]
+Description=Neko Agent (${name})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${runner}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+ printf '%s\n' "$unit_path"
+}
+
+write_openwrt_init() {
+ name="$1"
+ runner="$2"
+ service="$(service_name_for_instance "$name")"
+ init_path="/etc/init.d/${service}"
+ cat > "$init_path" <<EOF
+#!/bin/sh /etc/rc.common
+
+USE_PROCD=1
+START=95
+STOP=10
+
+start_service() {
+ procd_open_instance
+ procd_set_param command "${runner}"
+ procd_set_param respawn 3600 5 5
+ procd_set_param stdout 1
+ procd_set_param stderr 1
+ procd_close_instance
+}
+EOF
+ chmod +x "$init_path"
+ printf '%s\n' "$init_path"
+}
+
+write_launchd_plist() {
+ name="$1"
+ runner="$2"
+ launch_dir="${HOME}/Library/LaunchAgents"
+ label="io.neko-master.agent.${name}"
+ plist_path="${launch_dir}/${label}.plist"
+ mkdir -p "$launch_dir"
+ cat > "$plist_path" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>Label</key>
+ <string>${label}</string>
+
+ <key>ProgramArguments</key>
+ <array>
+ <string>${runner}</string>
+ </array>
+
+ <key>RunAtLoad</key>
+ <true/>
+ <key>KeepAlive</key>
+ <true/>
+
+ <key>StandardOutPath</key>
+ <string>$(log_file "$name")</string>
+ <key>StandardErrorPath</key>
+ <string>$(log_file "$name")</string>
+</dict>
+</plist>
+EOF
+ printf '%s\n' "$plist_path"
+}
+
+enable_autostart_systemd() {
+ name="$1"
+ runner="$2"
+ service="$(service_name_for_instance "$name")"
+ write_systemd_unit "$name" "$runner" >/dev/null
+ systemctl daemon-reload
+ systemctl enable "$service" >/dev/null
+ systemctl restart "$service"
+}
+
+enable_autostart_openwrt() {
+ name="$1"
+ runner="$2"
+ service="$(service_name_for_instance "$name")"
+ init_path="$(write_openwrt_init "$name" "$runner")"
+ "$init_path" enable
+ "$init_path" restart
+}
+
+enable_autostart_launchd() {
+ name="$1"
+ runner="$2"
+ plist_path="$(write_launchd_plist "$name" "$runner")"
+ launchctl unload "$plist_path" >/dev/null 2>&1 || true
+ launchctl load "$plist_path"
+}
+
+enable_autostart_cron() {
+ name="$1"
+ runner="$2"
+ marker="# nekoagent-autostart-${name}"
+ line="@reboot ${runner} >/dev/null 2>&1 ${marker}"
+ old_cron="$(crontab -l 2>/dev/null || true)"
+ {
+ printf '%s\n' "$old_cron" | grep -v "$marker" || true
+ printf '%s\n' "$line"
+ } | crontab -
+}
+
+disable_autostart_systemd() {
+ name="$1"
+ service="$(service_name_for_instance "$name")"
+ unit_path="/etc/systemd/system/${service}.service"
+ systemctl disable "$service" >/dev/null 2>&1 || true
+ systemctl stop "$service" >/dev/null 2>&1 || true
+ rm -f "$unit_path"
+ systemctl daemon-reload >/dev/null 2>&1 || true
+}
+
+disable_autostart_openwrt() {
+ name="$1"
+ service="$(service_name_for_instance "$name")"
+ init_path="/etc/init.d/${service}"
+ if [ -x "$init_path" ]; then
+ "$init_path" disable >/dev/null 2>&1 || true
+ "$init_path" stop >/dev/null 2>&1 || true
+ fi
+ rm -f "$init_path"
+}
+
+disable_autostart_launchd() {
+ name="$1"
+ label="io.neko-master.agent.${name}"
+ plist_path="${HOME}/Library/LaunchAgents/${label}.plist"
+ launchctl unload "$plist_path" >/dev/null 2>&1 || true
+ rm -f "$plist_path"
+}
+
+disable_autostart_cron() {
+ name="$1"
+ marker="# nekoagent-autostart-${name}"
+ old_cron="$(crontab -l 2>/dev/null || true)"
+ printf '%s\n' "$old_cron" | grep -v "$marker" | crontab -
+}
+
+cmd_enable_autostart() {
+ name="$1"
+ ensure_dirs
+ load_config "$name"
+ runner="$(generate_runner_script "$name")"
+ manager="$(detect_service_manager)"
+ require_linux_root "$manager"
+
+ if is_running "$name"; then
+ cmd_stop "$name" || true
+ fi
+
+ case "$manager" in
+ openwrt)
+ enable_autostart_openwrt "$name" "$runner"
+ ;;
+ systemd)
+ enable_autostart_systemd "$name" "$runner"
+ ;;
+ launchd)
+ enable_autostart_launchd "$name" "$runner"
+ ;;
+ cron)
+ enable_autostart_cron "$name" "$runner"
+ cmd_start "$name"
+ ;;
+ *)
+ err "autostart is not supported on this system"
+ exit 1
+ ;;
+ esac
+
+ log "autostart enabled for '$name' via $manager"
+}
+
+cmd_disable_autostart() {
+ name="$1"
+ manager="$(detect_service_manager)"
+ require_linux_root "$manager"
+ case "$manager" in
+ openwrt)
+ disable_autostart_openwrt "$name"
+ ;;
+ systemd)
+ disable_autostart_systemd "$name"
+ ;;
+ launchd)
+ disable_autostart_launchd "$name"
+ ;;
+ cron)
+ disable_autostart_cron "$name"
+ ;;
+ *)
+ ;;
+ esac
+ rm -f "$(runner_file "$name")"
+ log "autostart disabled for '$name'"
+}
+
# Query GitHub releases API for the latest agent tag (e.g. "agent-v0.2.0").
# Returns empty string on failure — callers must handle this gracefully.
get_latest_remote_tag() {
@@ -293,6 +606,8 @@ Usage:
$PROG restart <name> Restart agent instance
$PROG status <name> Show instance status
$PROG logs <name> Tail logs
+ $PROG enable-autostart <name> Register boot autostart and start via service manager
+ $PROG disable-autostart <name> Remove boot autostart registration
$PROG list List configured instances
$PROG restart-all Restart all running instances
$PROG upgrade [version] Upgrade manager+binary and restart running instances
@@ -340,6 +655,9 @@ Examples:
# Check status
$PROG status home-surge
+ # Register startup persistence
+ $PROG enable-autostart home-surge
+
# View logs
$PROG logs home-surge
@@ -695,12 +1013,15 @@ cmd_upgrade_global() {
cmd_remove() {
name="$1"
+ cmd_disable_autostart "$name" >/dev/null 2>&1 || true
+
if is_running "$name"; then
cmd_stop "$name"
fi
rm -f "$(pid_file "$name")"
rm -f "$(log_file "$name")"
+ rm -f "$(runner_file "$name")"
cf="$(config_file "$name")"
if [ -f "$cf" ]; then
@@ -742,7 +1063,7 @@ main() {
fi
cmd_add "$@"
;;
- start|stop|restart|status|logs)
+ start|stop|restart|status|logs|enable-autostart|disable-autostart)
if [ "$#" -ne 1 ]; then
usage
exit 1
@@ -753,6 +1074,8 @@ main() {
restart) cmd_stop "$1" || true; cmd_start "$1" ;;
status) cmd_status "$1" ;;
logs) cmd_logs "$1" ;;
+ enable-autostart) cmd_enable_autostart "$1" ;;
+ disable-autostart) cmd_disable_autostart "$1" ;;
esac
;;
upgrade)
diff --git a/docs/agent/install.en.md b/docs/agent/install.en.md
index 90ac2d3..16af44f 100644
--- a/docs/agent/install.en.md
+++ b/docs/agent/install.en.md
@@ -31,7 +31,7 @@ Optional env:
- `NEKO_GATEWAY_TOKEN`: gateway auth token
- `NEKO_AGENT_VERSION`: `latest` (default) or explicit tag like `agent-v0.2.0`
- `NEKO_INSTALL_DIR`: install directory (default `$HOME/.local/bin`)
-- `NEKO_AUTO_START`: `true|false` (default `true`)
+- `NEKO_AUTO_START`: `true|false` (default `true`, starts immediately and auto-registers boot autostart)
- `NEKO_LOG`: `true|false` (default `true`)
- `NEKO_LOG_FILE`: runtime log file path
- `NEKO_PACKAGE_URL`: custom package URL override
@@ -95,9 +95,10 @@ The `nekoagent` manager stores:
## Autostart on system boot
-By default `neko-agent` runs as a background process managed by `nekoagent`. It does not
-register a system service automatically. For production deployments, set up a system service
-so the agent survives reboots.
+Since `agent-v0.2.1`, when `NEKO_AUTO_START=true` the installer automatically attempts to
+register boot autostart (systemd / OpenWrt procd / launchd / cron fallback).
+If permissions are insufficient or the platform is unsupported, configure a system service
+manually so the agent survives reboots.
### Linux — systemd
diff --git a/docs/agent/install.md b/docs/agent/install.md
index 4ae7986..0781b29 100644
--- a/docs/agent/install.md
+++ b/docs/agent/install.md
@@ -31,7 +31,7 @@ curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/
- `NEKO_GATEWAY_TOKEN`:网关认证 token
- `NEKO_AGENT_VERSION`:`latest`(默认)或具体标签如 `agent-v0.2.0`
- `NEKO_INSTALL_DIR`:安装目录(默认 `$HOME/.local/bin`)
-- `NEKO_AUTO_START`:`true|false`(默认 `true`)
+- `NEKO_AUTO_START`:`true|false`(默认 `true`,安装后立即启动并自动注册开机自启)
- `NEKO_LOG`:`true|false`(默认 `true`)
- `NEKO_LOG_FILE`:运行时日志文件路径
- `NEKO_PACKAGE_URL`:自定义软件包 URL
@@ -78,8 +78,8 @@ nekoagent uninstall
## 开机自启配置
-`neko-agent` 默认以后台进程方式运行,由 `nekoagent` 管理,不自动注册系统服务。
-生产环境建议配置系统服务,确保重启后自动恢复运行。
+从 `agent-v0.2.1` 开始,安装脚本在 `NEKO_AUTO_START=true` 时会自动尝试注册系统开机自启(systemd / OpenWrt procd / launchd / cron 回退)。
+若当前环境权限不足或不支持自动注册,可使用手动方式配置系统服务,确保重启后自动恢复运行。
### Linux — systemd