How deposist/s-ui-rus-inst works
1. This repository is a single Go-based control plane for Sing-Box. It combines a web admin panel, a subscription service, local persistence, and the runtime logic needed to create and manage Sing-Box configs and registrations. The frontend is a separate Vue 3 app built into the backend as static assets.
2. The main runtime entrypoints are main.go, app/app.go, and core/main.go. cmd/ contains the CLI/admin tooling and versioned database migration entrypoints, while install.sh, s-ui.sh, systemd units, Docker files, and Windows scripts handle deployment rather than product logic.
3. The HTTP surface is split into two user-facing boundaries: the panel/API and the subscription endpoint. api/ holds request handlers, session handling, and rate limiting for the admin UI; sub/ handles subscription generation and export formats. The README’s default paths map to this split: /app/ for the panel and /sub/ for subscriptions.
4. The backend is layered around a service façade in service/. Those packages model the domain objects the panel edits: users/clients, settings, inbounds, outbounds, endpoints, TLS, statistics, WARP, and server/panel configuration. This is the layer that translates HTTP requests into persisted state and Sing-Box-facing configuration.
5. The core Sing-Box orchestration lives in core/. It contains endpoint registration, outbound checks, connection tracking, and statistics aggregation. The register_* files show platform/feature-specific registration strategies, including naive and Tailscale variants, with stub files for builds where those integrations are unavailable.
6. Persistence is centered in database/. database/db.go and database/model/ define the stored schema for inbounds, outbounds, endpoints, services, and other panel state. database/adapt.go and the cmd/migration/ package handle schema evolution and legacy database upgrades, while database/backup.go manages export/import and restore workflows.
7. The panel has a scheduling subsystem in cronjob/ for recurring maintenance tasks. These jobs include stats collection, cleanup, depletion checks, core checks, and WAL checkpointing, which indicates the app keeps both live operational state and historical usage metrics.
8. Subscription generation and serialization are factored out into sub/ and util/. The util/ package contains helpers for base64, link generation, JSON conversion, and subscription metadata; sub/ turns stored service/topology data into consumable subscription responses such as link, JSON, and Clash-compatible outputs.
9. The frontend is a fairly large Vue/Vite application under frontend/, organized by views, layouts, modal dialogs, protocol-specific editors, and shared components. It talks to the backend through frontend/src/plugins/api.ts, with local state in the store and locale files for multi-language UI. The backend serves the built frontend from web/.
10. Security and request-boundary concerns are explicit parts of the architecture. api/rateLimit.go, api/session.go, and middleware like middleware/domainValidator.go protect the admin surface; the README also documents trusted-proxy handling and subscription URL validation. That means client IP, login, and external fetch behavior are intentionally gated before data reaches the service layer.
11. network/ abstracts listener behavior, including auto-HTTPS and bind/listen handling. This is the transport boundary between the panel/subscription HTTP servers and the host network, and it is also where listen-address resilience and TLS behavior are enforced.
12. config/, logger/, and util/common/ provide cross-cutting infrastructure: versioning/name metadata, structured logging, and small shared utilities such as password and random helpers. These are support layers used by both the API/service code and the maintenance/migration code.
13. The project is designed for multiple deployment modes but the architecture stays the same: one long-running backend process, optional Sing-Box binary managed by that process, a browser-based admin SPA, and persistent state in a local DB directory. Docker, systemd, and Windows packaging are operational wrappers around that same core split.
Main entry points: app.go App boot · panel.go Service façade · apiHandler.go Panel API · main.go Core runtime
Components 24
Runtime
Long-running backend entrypoints and request-serving boundaries
- main · Top-level process bootstrap
main.go - App boot · Wires the backend runtime together
app/app.go - Panel API · Admin panel request surface
api/apiHandler.go - Session guard · Login/session and boundary checks
api/session.go - Rate limit · Protects the admin API from abuse
api/rateLimit.go - Sub endpoint · Subscription request surface
sub/subHandler.go
Domain
Service façade and Sing-Box orchestration
- Sub pipeline · Builds subscription responses and formats
sub/subService.go - Service façade · Coordinates panel edits into persisted state
service/panel.go - Inbounds · Inbound configuration management
service/inbounds.go - Outbounds · Outbound configuration management
service/outbounds.go - Users · Client and user lifecycle
service/user.go - Stats · Usage and operational counters
service/stats.go - Core runtime · Registers endpoints and manages runtime state
core/main.go - Registrations · Feature-specific endpoint registration strategies
core/register.go - Tracking · Connection tracking and statistics aggregation
core/tracker_conn.go
Data
Local persistence, migrations, and backup
UI
Vue admin panel and static asset delivery
- Admin SPA · Browser-based admin interface built from Vue/Vite
frontend/src/main.ts - Static web · Serves the built frontend assets
web/web.go
Support
Cross-cutting infrastructure and transport
- Network I/O · Bind/listen handling and auto-HTTPS transport
network/listen.go - Domain guard · Validates request boundaries and trusted domains
middleware/domainValidator.go - Config · Versioning and name metadata
config/config.go - Logger · Structured application logging
logger/logger.go
Connections 30
- main → App boot: starts · Main process boots the application runtime
- App boot → Panel API: hosts · Starts the panel/API surface
- App boot → Sub endpoint: hosts · Starts the subscription surface
- App boot → Core runtime: runs · Launches Sing-Box orchestration
- App boot → Scheduler: schedules · Enables recurring maintenance jobs
- App boot → Network I/O: binds · Uses transport/listener abstraction for server sockets
- App boot → Static web: serves · Exposes built frontend assets
- Panel API → Session guard: guards · Session handling protects admin requests
- Panel API → Rate limit: throttles · Rate limiting sits in front of the API
- Panel API → Service façade: mutates · API translates user actions into domain operations
- Sub endpoint → Sub pipeline: builds · Subscription handler delegates serialization and export
- Sub pipeline → Service façade: reads · Subscription generation uses stored service topology
- Service façade → Inbounds: coordinates · Facade delegates inbound edits
- Service façade → Outbounds: coordinates · Facade delegates outbound edits
- Service façade → Users: coordinates · Facade delegates client/user management
- Service façade → Stats: coordinates · Facade exposes operational stats
- Service façade → Database: persists · Domain state is stored locally
- Service façade → Core runtime: syncs · Service layer feeds Sing-Box runtime state
- Core runtime → Registrations: registers · Core uses registration strategies for endpoints
- Core runtime → Tracking: tracks · Core maintains connection and stats state
- Core runtime → Database: loads · Core reads persisted configuration and state
- Database → Backup: exports · Database supports backup and restore flows
- Database → Scheduler: maintains · Jobs clean up and checkpoint persisted state
- Scheduler → Stats: collects · Scheduled jobs gather and prune usage stats
- Network I/O → Domain guard: enforces · Listener/request boundary enforces trusted-domain rules
- App boot → Config: configures · Runtime setup is driven by application config
- App boot → Logger: logs · Bootstrap and services share structured logging
- Admin SPA → Panel API: calls · SPA talks to the backend API
- Admin SPA → Sub endpoint: uses · UI surfaces subscription-related features
- Static web → Admin SPA: serves · Backend serves the compiled admin SPA