itdoginfo/podkop

Purpose and Deployment

Podkop is an OpenWrt 24.10+ traffic-routing package built around sing-box. It routes selected resources through a tunnel while leaving other traffic direct, and modifies Dnsmasq and sing-box configuration at service startup. Packaging targets both APK and IPK ecosystems: podkop/Makefile, luci-app-podkop/Makefile, install.sh.

Runtime Entry Points

The device-side service entry point is the init script podkop/files/etc/init.d/podkop, which invokes the operational shell program podkop/files/usr/bin/podkop. Default persistent configuration is UCI-backed at podkop/files/etc/config/podkop. The LuCI package registers its UI/menu and RPC permissions through luci-app-podkop/root/usr/share/luci/menu.d/luci-app-podkop.json and luci-app-podkop/root/usr/share/rpcd/acl.d/luci-app-podkop.json.

Routing and Configuration Core

The shell runtime owns system integration: nftables manipulation, routing rulesets, logging, and sing-box configuration generation/management. Its key boundaries are:

• Service orchestration: podkop/files/usr/bin/podkop, podkop/files/etc/init.d/podkop

• Firewall/ruleset layer: podkop/files/usr/lib/nft.sh, podkop/files/usr/lib/rulesets.sh

• sing-box adapter layer: podkop/files/usr/lib/sing_box_config_facade.sh, podkop/files/usr/lib/sing_box_config_manager.sh

UCI configuration feeds this runtime; the runtime materializes/updates sing-box and networking state rather than exposing those internals directly to the UI.

LuCI Frontend Architecture

fe-app-podkop is a TypeScript frontend compiled and shipped into the LuCI app’s static views. Its bootstrap is fe-app-podkop/src/main.ts; domain composition and remote calls are centered in fe-app-podkop/src/podkop/index.ts and fe-app-podkop/src/podkop/api.ts. The checked-in LuCI view entrypoints include luci-app-podkop/htdocs/luci-static/resources/view/podkop/main.js, luci-app-podkop/htdocs/luci-static/resources/view/podkop/dashboard.js, and luci-app-podkop/htdocs/luci-static/resources/view/podkop/diagnostic.js.

The frontend operates in the LuCI browser runtime, using LuCI/RPC interfaces and shell-backed methods rather than a separate web server.

UI State, Services, and Live Data

Frontend services separate tab selection, local state, core lifecycle calls, logging, and socket/event handling:

fe-app-podkop/src/podkop/services/core.service.ts,

fe-app-podkop/src/podkop/services/store.service.ts,

fe-app-podkop/src/podkop/services/socket.service.ts.

Data flows from API/fetcher and custom/shell method layers into stores and tab controllers:

fe-app-podkop/src/podkop/fetchers/fetchServicesInfo.ts,

fe-app-podkop/src/podkop/methods/shell/callBaseMethod.ts,

fe-app-podkop/src/podkop/methods/custom/getConfigSections.ts.

This is the primary UI-to-router control boundary.

Dashboard and Diagnostics

The dashboard renders service/configuration-oriented sections and widgets, with its controller coordinating load/update behavior: fe-app-podkop/src/podkop/tabs/dashboard/initController.ts, fe-app-podkop/src/podkop/tabs/dashboard/render.ts.

Diagnostics is a distinct staged check system with stored results and executable checks for DNS, FakeIP, nftables, configuration sections, and sing-box: fe-app-podkop/src/podkop/tabs/diagnostic/diagnostic.store.ts, fe-app-podkop/src/podkop/tabs/diagnostic/checks/runNftCheck.ts, fe-app-podkop/src/podkop/tabs/diagnostic/checks/runSingBoxCheck.ts.

External Dependencies and Constraints

Material dependencies are OpenWrt/LuCI, UCI, rpcd, Dnsmasq, nftables, and sing-box; the dashboard also depends on sing-box’s Clash API and is documented as HTTP-only. Release/build infrastructure includes package Dockerfiles (Dockerfile-apk, Dockerfile-ipk) and SDK variants under sdk/.