mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-01-17 19:19:34 +00:00
55 lines
2.4 KiB
Markdown
55 lines
2.4 KiB
Markdown
|
# AGENTS.md (3x-ui)
|
|||
|
|
|
|||
|
|
This repo is **primarily Go**: a Gin-based web panel that manages an **Xray-core** process and stores state in a **SQLite** DB.
|
|||
|
|
|
|||
|
|
## Quick commands (repo root)
|
|||
|
|
|
|||
|
|
- **Run (dev, no root needed)**:
|
|||
|
|
- Ensure writable paths:
|
|||
|
|
- `mkdir -p ./x-ui ./bin ./log`
|
|||
|
|
- `export XUI_DB_FOLDER="$(pwd)/x-ui"`
|
|||
|
|
- `export XUI_BIN_FOLDER="$(pwd)/bin"`
|
|||
|
|
- `export XUI_LOG_FOLDER="$(pwd)/log"`
|
|||
|
|
- `export XUI_DEBUG=true` (loads templates/assets from disk; see `web/AGENTS.md`)
|
|||
|
|
- Start: `go run .`
|
|||
|
|
- Panel defaults (fresh DB): `http://localhost:2053/` with **admin/admin**
|
|||
|
|
|
|||
|
|
- **Build**: `go build -ldflags "-w -s" -o build/x-ui main.go`
|
|||
|
|
- **Format**: `gofmt -w .`
|
|||
|
|
- **Tests**: `go test ./...`
|
|||
|
|
- **Basic sanity**: `go vet ./...`
|
|||
|
|
|
|||
|
|
## Docker
|
|||
|
|
|
|||
|
|
- **Compose**: `docker compose up --build`
|
|||
|
|
- Uses `network_mode: host` and mounts:
|
|||
|
|
- `./db/` → `/etc/x-ui/` (SQLite DB lives at `/etc/x-ui/x-ui.db`)
|
|||
|
|
- `./cert/` → `/root/cert/`
|
|||
|
|
|
|||
|
|
## Layout / where things live
|
|||
|
|
|
|||
|
|
- **Entry point**: `main.go` (starts the web server + subscription server; handles signals)
|
|||
|
|
- **Config**: `config/` (env-driven defaults; DB path, bin path, log folder)
|
|||
|
|
- **DB (SQLite via GORM)**: `database/` (+ `database/model/`)
|
|||
|
|
- **Web panel**: `web/` (Gin controllers, templates, embedded assets, i18n)
|
|||
|
|
- **Subscription server**: `sub/`
|
|||
|
|
- **Xray process management**: `xray/` (binary path naming, config/log paths, process wrapper)
|
|||
|
|
- **Operational scripts**: `install.sh`, `update.sh`, `x-ui.sh` (production/admin tooling; be cautious editing)
|
|||
|
|
|
|||
|
|
## Important environment variables
|
|||
|
|
|
|||
|
|
- **`XUI_DEBUG=true`**: enables dev behavior (Gin debug + loads `web/html` and `web/assets` from disk).
|
|||
|
|
- **`XUI_DB_FOLDER`**: DB directory (default: `/etc/x-ui` on non-Windows). DB file is `<folder>/x-ui.db`.
|
|||
|
|
- **`XUI_BIN_FOLDER`**: where Xray binary + `config.json` + `geo*.dat` live (default: `bin`).
|
|||
|
|
- **`XUI_LOG_FOLDER`**: log directory (default: `/var/log` on non-Windows).
|
|||
|
|
- **`XUI_LOG_LEVEL`**: `debug|info|notice|warning|error`.
|
|||
|
|
|
|||
|
|
## Agent workflow guidelines
|
|||
|
|
|
|||
|
|
- **Prefer small, surgical changes**: this is a production-oriented project (panel + system scripts).
|
|||
|
|
- **Don’t run** `install.sh` / `update.sh` in dev automation: they expect **root** and mutate the system.
|
|||
|
|
- **When touching templates/assets**: ensure it works in both **debug** (disk) and **production** (embedded) modes.
|
|||
|
|
- **Security**: treat any change in `web/controller`, `web/service`, and shell scripts as security-sensitive.
|
|||
|
|
|
|||
|
|
|