miaomiaowu: a self-hosted manager for Clash subscriptions and node traffic

A panel for people with too many subscriptions

miaomiaowu, the Miaomiaowu personal Clash subscription management system, is a lightweight, easy to deploy system for Clash subscriptions. Its stated purpose is node management, generating subscriptions, importing external subscription nodes and aggregating traffic, and it supports traffic information from Nezha, DStatus and Komari probes.

The feature list divides into two halves. The traffic half covers monitoring, with aggregation of traffic from probe servers and from external subscriptions, and a 30 day traffic usage trend chart. The subscription half is where the work is. You can upload a cat config file or import from another subscription URL to produce a subscription, you can import your own nodes or provider nodes, and you can add, edit and delete proxy nodes. From those you generate a subscription, either with custom rules or from a template for a quick start. The group configuration is a drag and drop editor for grouping proxy nodes, and it supports chain proxies. On top of that there is user management with administrator and normal user roles and subscription permission management, light and dark themes, and a responsive design that the readme itself notes is not fully adapted to mobile and desktop.

There is a live demo at demo.miaomiaowu.net with the credentials test and test123, and the documentation site is at docs.miaomiaowu.net.

The project also publishes a disclaimer. It says the program is for study and exchange only and must not be used for illegal purposes, that use must comply with local law, and that the author accepts no responsibility for what users do with it.

Docker deployment with three mounted directories

The Docker route is the recommended one, and the readme says it needs no dependency environment at all. The image provides both linux/amd64 and linux/arm64 architectures and the correct one is matched on pull. The basic run is a single docker run command.

docker run -d \
  --user root \
  --name miaomiaowu \
  -p 8080:8080 \
  -v $(pwd)/mmw-data:/app/data \
  -v $(pwd)/subscribes:/app/subscribes \
  -v $(pwd)/rule_templates:/app/rule_templates \
  ghcr.io/iluobei/miaomiaowu:latest

The port mapping is documented as adjustable. The three volumes have distinct jobs, and the readme is explicit that the data volume exists so the database survives a container rebuild. The subscribes volume holds the subscription configuration files, and the rule_templates volume holds the rule file templates. The readme also notes that you do not need to mount any of the three if you do not know what they are for, which is an odd but honest framing, and it warns you to back up the directories regularly.

There is a Compose file as well, and it adds the environment variables and a health check that the run command does not show.

services:
  miaomiaowu:
    image: ghcr.io/iluobei/miaomiaowu:latest
    container_name: miaomiaowu
    restart: unless-stopped
    user: root
    environment:
      - PORT=8080
      - DATABASE_PATH=/app/data/traffic.db
      - LOG_LEVEL=info
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/"]

The JWT_SECRET environment variable is optional and is the token signing key, and the readme recommends setting it to a random string. LOG_LEVEL is the other variable mentioned, and the readme says more environment variables are covered in its own section. The health check uses wget in spider mode against the root URL, which is why wget is in the final image.

A Go backend with a JavaScript frontend and a pure Go SQLite driver

The repository layout is unusual enough to be worth decoding, because the top level listing shows both a Go module and a frontend directory. There is a go.mod at the root with the module named miaomiaowu and a go directive of 1.26, and there is a miaomiaowu/ directory that the Dockerfile copies package files from, which is where the frontend lives. The Dockerfile builds it in stages: a node:20-slim stage runs npm ci and npm run build to produce the frontend into internal/web/dist, and a golang:1.26-bookworm stage cross compiles the backend with CGO_ENABLED=0, producing a binary named server from ./cmd/server.

The comment on the SQLite dependency is worth reading. It uses the pure Go implementation modernc.org/sqlite, so no CGO is needed and the release binaries match what the container produces. The other direct dependencies describe what the application does. MMWOrg/mmwX-plugins/proxyparser is the Clash configuration parser, and it is the piece the changelog spends a lot of words on. gorilla/websocket handles the live connection to the browser, dop251/goja is a JavaScript interpreter, which fits a rule editor that has to evaluate expressions. pquerna/otp is a one time password library, used for the two factor flow in user management. gopkg.in/yaml.v3 is the YAML parser, and golang.org/x/crypto covers the password hashing.

The build is deliberate about architecture. The frontend stage is pinned to the native build platform with a comment explaining that this avoids running arm64 under QEMU emulation, and the backend is a native cross compile using TARGETOS and TARGETARCH, with the same reason given. The final stage is debian:bookworm-slim with ca-certificates for HTTPS requests, tzdata, gosu for privilege dropping and wget for the health check, and the image creates a non-root user before the application starts.

Changelog entries that show where the work actually goes

The changelog in the readme is unusually detailed and it points at the real engineering effort in the project, which is not the panel but the YAML handling.

The v0.8.9 entry describes a fix to the logic that removes quotes when writing YAML back. The previous approach guessed with a regular expression where a double quoted string was and whether removing the quotes was safe, and that wrote broken configurations, splitting names containing a comma or square brackets in a streaming list into separate items, and rewriting a rule's unicode escape into the literal character. The new approach takes the position, the decoded value and the context from the parser itself, only unquotes something that can be written plain, and re-parses the whole document at the end to compare node by node with the original, falling back to keeping the quotes if they differ. The entry mentions a test with 2000 random payloads written back three times in a row.

The same entry covers the client type table. A new MeowX client type was added, the automatic detection gained fallbacks for the v2ray family and for clients that only report a version string, and the readme notes that this table doubles as an allow list for blocking unknown subscription user agents, because clients configured to block would previously get a 403.

The v0.8.8 entry added binding a V2 template to an aggregated subscription with automatic conversion to V3, and v0.8.7 fixed a bug where a mieru node using a port range could not be saved, and made the latest Docker tag always provide an arm64 build. The v0.8.6 entry upgraded proxyparser to v0.2.9 to fix port hopping being lost when a host was written with a port range for hy2 and hysteria.

All of this points to one conclusion about the project. The difficult part is not the dashboard, it is faithfully round tripping a Clash configuration without corrupting it, and the changelog shows the author treating that as the priority.

Where miaomiaowu is the wrong tool

Three cases argue against it. The first is a user with one subscription from one provider. The whole value of the system is aggregation, and the aggregation of a single source is a copy operation you can do in the provider's own dashboard. The node management, the visual group editor and the traffic aggregation all need volume to earn their keep.

The second case is a user of a different proxy client. The parser is Clash specific, the generated subscriptions are Clash configurations, and the client type table covers Clash clients and their derivatives. A Shadowsocks or sing-box or v2ray user gets nothing here, even though the underlying idea of consolidating subscriptions would apply.

The third case is a security sensitive deployment. The system holds the proxy node credentials for every source you import, and it exposes them to whoever can reach the panel and has the right role. The readme notes that the responsive design is not fully adapted, that the demo instance ships with the credentials test and test123, and that the container runs as root with gosu used to drop privileges afterwards. The JWT_SECRET is optional, and if you leave it unset the default signing key is in use, so a deployment on a reachable host with the default key is a bad idea. The SQLite file holding the traffic history and the node configuration lives in a mounted directory that the readme tells you to back up, and the backup is where the credentials end up too.

On the operational side, the one click install path is the roughest. The readme warns that version 0.1.1 changed the service name, so a script based update is no longer possible and you have to reinstall, and the instructions for migrating from the old service name involve stopping and disabling a systemd unit, removing its files and copying the old data directory into place by hand. The newer quick-install.sh path avoids systemd and runs a single binary in place, which is simpler but leaves you without service management.

The licence is MIT, the project has no GitHub releases beyond the tagged v0.8.x line, and the release cadence is fast, with v0.8.7, v0.8.8 and v0.8.9 landing in eleven days in October 2026.

Editorial conclusion

miaomiaowu suits a Clash user who has several node sources and wants one place to import them, assemble subscriptions, and see how much traffic each source has used. It does not suit someone who only needs one subscription file from one provider, since the whole value is in the aggregation and the editor, and it does not suit a user of other proxy clients, because the parsing and generation are Clash specific. Before you deploy it, set JWT_SECRET to a random string and keep the three mounted directories backed up, and note that the last push was on 2026-10-16, two days after the v0.8.9 release.

Frequently asked questions

Official sources

1. iluobei/miaomiaowu on GitHub
2. Issues
3. Project website
4. README
5. Releases