Repository navigation
Development
The source is organized to keep the Go application buildable with the normal go build . command:
main.go Root executable entry point
internal/app/ Panel backend and Go tests
internal/mihomoconvert/ Mihomo sharing-link converter
web/ Embedded HTML, CSS, JavaScript, and assets
tests/ Browser regression scripts
scripts/ Local run/build/release/management scripts
deploy/ systemd and OpenRC service definitions
install.sh GitHub one-line Linux installer
Dockerfile, docker/ Docker image and entrypoint
The backend remains one internal Go package so its unexported validation and rendering helpers can be tested together. The frontend is a separate embedded package.
- Go 1.24 or newer to compile;
go.modpins the toolchain to Go 1.26.10 (the crypto/x509 fix for CVE-2026-111943), which thegocommand downloads automatically unlessGOTOOLCHAIN=local - Node.js for optional browser tests
- Mihomo executable for local runtime testing
- Playwright for the browser regression scripts
Run the application during development:
.\scripts\run.ps1or:
./scripts/run.shgo test ./...
go vet ./...The main application tests cover YAML compilation, subscriptions, WARP, Multi-control, inbound synchronization, cross-panel aggregation, migration, and settings validation.
Tests that start a real Mihomo core are skipped unless MUI_TEST_CORE points to a Mihomo executable:
MUI_TEST_CORE=/path/to/mihomo go test ./...For race testing of the networking and CLI paths:
go test -race ./... -run 'TestConfigureCLI|TestCrossSubscription|TestInboundSync|TestMesh'Build Windows, a Linux amd64 binary, and run the Go test suite:
.\scripts\build.ps1Build all published Linux Release archives:
.\scripts\build-release.ps1The release script emits:
m-ui-linux-386.tar.gz
m-ui-linux-amd64.tar.gz
m-ui-linux-arm64.tar.gz
m-ui-linux-armv5.tar.gz
m-ui-linux-armv6.tar.gz
m-ui-linux-armv7.tar.gz
m-ui-linux-s390x.tar.gz
Each archive contains one executable named m-ui-linux-<architecture>. The release workflow also builds m-ui-windows-amd64.zip, which contains m-ui.exe.
Builds accept MUI_VERSION. If it is not set, the scripts use a tag pointing at HEAD; otherwise they fall back to dev-<short-commit>. The linker flag is:
-ldflags="-s -w -X main.version=v0.2.0"
The value is returned by m-ui version and is also used in panel state, backup manifests, log messages, and the HTTP User-Agent.
The recommended workflow is triggered by tags matching v*. It should:
- Check out the repository with full history.
- Set up Go from
go.mod. - Validate the tag, run
go test ./..., and rungo vet ./.... - Build the seven Linux architectures and Windows amd64 with
CGO_ENABLED=0. - Inject
main.versionusingGITHUB_REF_NAME. - Verify archive contents and the amd64
versionoutput. - Create a GitHub Release using
contents: write. - Build the Docker image and push it to
ghcr.io/romanovcaesar/m-ui:<tag>(stable tags also updatelatest).
Use annotated semantic tags such as:
git tag -a v0.1.0 -m "m-ui v0.1.0"
git push origin v0.1.0Prerelease tags such as v0.2.0-rc.1 should be marked as prereleases. Do not reuse an existing public version.
The scripts under tests/ use Playwright to exercise Mihomo Basics, Outbound YAML editing, Multi-control, and WARP flows. Install the project test dependency in your own development environment and run the scripts with the test server running. These dependencies are not needed by the Linux runtime binary.
The panel, login page and subscription page have three themes, picked with the Panel Theme setting (uiTheme: shadcn, md3 or liquid; shadcn is the default). The server writes the theme into <html data-ui-theme="..."> when it serves index.html and login.html, and drops every <link> or <script> tagged data-ui-only="<other theme>" (internal/app/ui_theme.go), so a page only downloads its own theme. liquid-glass.css and the styles inside the pages are the shared base; theme-shadcn.css and theme-md3.css restyle that base and also provide the layout rules the Liquid Glass files would otherwise add. The subscription page is a Go template: it loads the Liquid Glass controls for liquid and subscription-themes.css for the other two. Fonts live in web/fonts (declared in fonts.css); icons-lucide.js and icons-material.js replace the sprite of sf-symbols.js with icons of the same sf-* ids, which a Go test checks. When you add a page or a control, check it in all three themes, in light and dark mode and at phone width.
The Liquid Glass theme imitates Apple's iOS 26 / macOS 26 Liquid Glass. LIQUID-GLASS.md in the repository describes where each control lives and how it was ported; liquid-glass-web-guide.md is a reusable write-up of the approach for other web projects.
When changing a protocol field:
- Confirm the corresponding Mihomo version behavior.
- Update the Go model, normalization, YAML rendering, share-link generation, and UI field together.
- Add a focused Go regression test.
- Check that unsupported fields are not accidentally emitted to the core.
- Run
go test ./...andgo vet ./.... - Add any new interface text in all 11 languages (
web/i18n.jsfor English and Simplified Chinese,web/i18n-locales.jsfor the rest); the Go tests check that every catalog is complete. - Update the relevant Wiki page.
Never commit data/, generated binaries, build caches, certificates, private keys, pairing state, or local logs.