108 lines
5.6 KiB
Markdown
108 lines
5.6 KiB
Markdown
# 01. System Architecture & Core Concepts
|
||
|
||
## 1. High-Level Overview
|
||
|
||
**Tachyon** is an enterprise-grade, lightweight traffic orchestration, multi-protocol proxying, and DPI anti-censorship platform built natively for **OpenWrt** (supporting 23.05, 24.10, 25.x, and SNAPSHOT).
|
||
|
||
```mermaid
|
||
graph TD
|
||
Client[LAN Clients] -->|TCP/UDP| Router[OpenWrt Router]
|
||
Router --> NFT[nftables: inet TachyonTable]
|
||
|
||
NFT -->|Direct List / 0ms| WAN[Direct WAN Gateway]
|
||
NFT -->|NFQueue Desync| Zapret[Zapret v1 / v2 nfqws/2]
|
||
NFT -->|SOCKS Desync| ByeDPI[ByeDPI ciadpi]
|
||
NFT -->|TProxy / Redirect| SingBox[sing-box Core v1.11+]
|
||
|
||
SingBox -->|VLESS Reality / H2 / WG| VPS[External VPS / Global Web]
|
||
Zapret --> WAN
|
||
ByeDPI --> WAN
|
||
|
||
subgraph Tachyon Control Plane
|
||
UCODE[ucode Core Runtime] --> NFT
|
||
UCODE --> SingBox
|
||
UCODE --> Zapret
|
||
UCODE --> ByeDPI
|
||
Watchdog[Autonomous Watchdog 5-15s] --> UCODE
|
||
AIDoctor[AI Doctor v2.5 / Local Doctor] --> Watchdog
|
||
Telegram[Telegram Bot Daemon] --> UCODE
|
||
RestAPI[HTTP REST Agent API / OpenAPI 3.0] --> UCODE
|
||
LuCI[LuCI TypeScript Web UI] --> UCODE
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Core Architectural Pillars
|
||
|
||
### 2.1. Native ucode Runtime (Zero Heavy Runtimes)
|
||
* All control plane logic, UCI manipulation, config generation, health checks, and JSON APIs are written in **ucode**, OpenWrt's native C-like scripting language.
|
||
* **Benefits**:
|
||
* Consumes $\approx$ 1–3 MB RAM (contrasted with 30–60 MB for Python/Node).
|
||
* Executes directly in C-speed with native bindings to `libuci`, `libubus`, `libblobmsg`, and posix syscalls (`fs`, `math`, `socket`).
|
||
* Runs on routers with as little as 128 MB RAM.
|
||
|
||
### 2.2. Deterministic State & Atomic Writes
|
||
* All configuration changes (`/etc/config/tachyon`) and JSON runtime configurations (`/tmp/tachyon/sing-box.json`) use an **atomic write pattern** (`tmp_file + rename`):
|
||
```ucode
|
||
fs.writefile(tmp_path, json_str);
|
||
fs.rename(tmp_path, target_path);
|
||
```
|
||
This prevents file corruption during sudden power losses or kernel panics.
|
||
|
||
### 2.3. Dual Control Interfaces: LuCI & Headless Telegram/REST
|
||
1. **LuCI Web UI**: Modern TypeScript SPA (`fe-app-tachyon`) compiled into LuCI JS assets (`luci-app-tachyon`).
|
||
2. **Interactive Telegram Bot**: Embedded polling daemon with inline keyboards for on-the-fly server switching, rule updates, and instant diagnostics.
|
||
3. **HTTP REST Agent API**: Secure CGI endpoint (`/cgi-bin/tachyon-agent/`) with OpenAPI 3.0.3 spec for integration with LLM agents (ChatGPT Custom GPTs, Cursor, Claude Code, N8N).
|
||
|
||
---
|
||
|
||
## 3. Directory Layout & Repository Anatomy
|
||
|
||
```
|
||
tachyon/
|
||
├── tachyon/files/ # Core backend package root
|
||
│ ├── etc/
|
||
│ │ ├── config/tachyon # Main UCI configuration (chmod 600)
|
||
│ │ ├── init.d/tachyon # Procd service init script
|
||
│ │ └── uci-defaults/ # Post-installation default configs
|
||
│ ├── usr/
|
||
│ │ ├── bin/tachyon # Main CLI entrypoint wrapper
|
||
│ │ └── lib/tachyon/ # Modular ucode libraries (60+ modules)
|
||
│ │ ├── core/ # Low-level helpers, UCI, constants
|
||
│ │ ├── service/ # Lifecycle, Watchdog, APIs, Telegram
|
||
│ │ ├── diagnostics/ # AI Doctor, Local Doctor, Quick Fixes
|
||
│ │ ├── singbox/ # Config generator, DNS, routing
|
||
│ │ ├── providers/ # Zapret v1/v2, ByeDPI, NFQueue
|
||
│ │ ├── nft/ # nftables ruleset compiler & applier
|
||
│ │ ├── dns/ # dnsmasq & DNS routing coordinator
|
||
│ │ ├── components/ # Updater, package manager, hosts
|
||
│ │ ├── config/ # Validator, rule engine, migrations
|
||
│ │ └── subscription/ # Subscriptions fetcher & parser
|
||
├── luci-app-tachyon/ # OpenWrt LuCI package
|
||
│ ├── htdocs/luci-static/resources/view/tachyon/ # Compiled frontend JS bundle
|
||
│ ├── root/etc/uci-defaults/ # LuCI menu registration
|
||
│ └── po/ # Translations (ru, en)
|
||
├── fe-app-tachyon/ # Frontend TypeScript source
|
||
│ ├── src/ # TypeScript SPA source
|
||
│ ├── tsup.config.ts # Builds and patches LuCI baseclass
|
||
│ └── package.json # Dependencies (vitest, typescript, tsup)
|
||
├── tests/ # Comprehensive test suite (100+ shell tests)
|
||
├── build.sh # Release packager (ipk + apk)
|
||
├── install.sh # One-liner end-user installer
|
||
└── docs/ # Technical documentation & Knowledge Base
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Key Runtime Processes & Daemons
|
||
|
||
| Process | Role | Execution Model |
|
||
|---|---|---|
|
||
| `sing-box` | Core proxying & packet tunneling engine | Managed by procd (`/etc/init.d/tachyon`) |
|
||
| `nfqws` / `nfqws2` | Local TCP/UDP packet desynchronizer (Zapret) | Spawned into background per configured rule |
|
||
| `ciadpi` | Local SOCKS desync proxy (ByeDPI) | Spawned on `127.0.0.1:1080` / custom port |
|
||
| `watchdog.uc` | State supervision, loop mitigation, self-healing | Background periodic daemon (every 5–15s) |
|
||
| `telegram.uc` | Telegram Bot Long-Polling Daemon | Procd-supervised background worker |
|
||
| `agent_api.uc` | HTTP REST Agent API Handler | Invoked on-demand via `uhttpd` CGI |
|