GoAccountHub

🌐 Language

English | 简体中文

📖 Introduction

GoAccountHub (GAH) is a user hub written in Go. It stores user metadata and supports multiple sub-users — called characters in this project — and comes with a Vue 3 management page plus an API for third-party applications. PostgreSQL is used as the database.

What it gives you:

• Single binary deployment — the built web UI is embedded with go:embed, so gah start serves the management page and the API on the same port. No extra static files on disk.
• Admin management — a root admin (kept in the config file, bypasses every permission check) plus normal admins with granular permissions; admins can be added, edited, deleted and listed.
• User & character management — users with arbitrary metadata (JSON / XML / YAML / plain text) and, when enabled, multiple characters per user.
• Application keys — keys used by third-party apps as the app_key cookie. A key user name is printable ASCII and immutable once created, the key itself is returned in full only once, and masked in every later response.
• Dashboard — counts of admins, users, characters, keys and login tokens, plus the current admin's permissions.

🧱 Tech Stack

Layer	Technology
Backend	Go 1.27, Gin, GORM, PostgreSQL
Frontend	Vue 3, Vite, Element Plus, vue-router, monaco-editor
CLI	urfave/cli v2

✅ Requirements

• Go 1.27 or newer
• PostgreSQL (17 recommended)
• Node.js ≥ 20.19 (22 or 24 LTS both work; CI uses 22) and npm — only needed to build the frontend

🚀 Build

If you download the binary directly, skip the following steps.

The build is driven by a magefile (build.go). Install mage once — the version is taken from go.mod:

go install github.com/magefile/mage

Command	What it does
mage frontend	npm ci + npm run build inside GAHFrontend, producing GAHFrontend/dist
mage build	native binary gah (Windows: gah.exe), embedding whatever is already in GAHFrontend/dist
mage all	frontend then build — one-click build with the UI embedded
mage cross	cross compiles windows / linux / darwin on amd64 and arm64 into bin/
mage allCross	frontend then cross — release build with the UI embedded

A cross build writes bin/GoAccountHub-<GAHversion>-<os>-<arch>[.exe], with the version read from GAHversion.

Manual equivalent — the order matters:

cd GAHFrontend
npm ci               # or npm install
npm run build        # produces GAHFrontend/dist
cd ..
go build -o gah .

⚠️ go build must run after npm run build. GAHFrontend/dist is embedded at compile time, so building first only embeds the placeholder GAHFrontend/dist/.gitkeep (tracked in git so that a fresh clone still compiles); the server then answers with a "frontend is not embedded" hint instead of the UI.

▶️ Start

1. Generate a config file (default name config.json):

   gah generate

   Use gah generate-test if you want a config pre-filled with test values — its default root admin password is 123.

2. Set the root admin password:

   gah password <your_password>

   ⚠️ The root admin has the highest privilege and can do anything in the system.

3. Open the config file and fill in the database settings:

   {
       "port": "8081",
       "database_name": "GoAccountHub",
       "database_host": "127.0.0.1",
       "database_port": "5432",
       "database_user": "postgres",
       "database_password": "postgres",
       "frontend_port": "8082",
       "root_admin_password_hash": "a665a45920422f9d417......",
       "root_admin_uu_hash": "0fbaf45ee863c0......",
       "switch_config": {
           "allow_multi_character": true,
           "allow_admin_logout": false
       }
   }

   Field	Description
   port	Port of the API server; it also serves the embedded web UI
   database_name	Database name
   database_host	Database host
   database_port	Database port
   database_user	Database username
   database_password	Database password
   frontend_port	Port of the Vite dev server; written into GAHFrontend/.env when the server starts
   root_admin_password_hash	Root admin password hash — generated by the CLI, no need to set it by hand
   root_admin_uu_hash	Root admin unique hash — generated by the CLI, no need to set it by hand
   switch_config.allow_multi_character	Whether an account may own multiple characters
   switch_config.allow_admin_logout	Whether admin logout is allowed (current implementation is broken, planned to be removed)

4. Start the server:

   gah start
   gah start -c ./config.json   # custom config path

5. Access it:

   • Web UI: http://localhost:<your_port>/
   • API: http://localhost:<your_port>/api/v1/...

   Log in with the root account and the password from step 2. Any path that is not an API route falls back to the web UI, so client side routes can be opened or refreshed directly.

ℹ️ Tables are created automatically on startup when they do not exist yet (AutoMigrate), and GAHFrontend/.env is created/overwritten from the config on every start.

🎨 Development

For frontend development, keep the API server running and start the Vite dev server — it gives you hot reload and proxies /api to the backend:

cd GAHFrontend
npm run dev

• The dev server port comes from PORT in GAHFrontend/.env, which gah start writes from frontend_port.
• A single-binary deployment does not need it: the Go process serves the UI itself.

🔑 Permission Model

Normal admins carry a permission object; a missing or false permission means HTTP 403:

Permission	Grants access to
can_add_admin	Add an admin
can_delete_admin	Delete an admin
can_edit_admin	Edit an admin
can_get_admin	Admin count / get / list
can_operate_user	All /api/v1/user/* admin endpoints
can_operate_character	All /api/v1/character/* admin endpoints
can_operate_app_key	All /api/v1/key/* admin endpoints

• The root admin bypasses all checks, cannot be deleted or edited through the API, and is not included in the admin list.
• The admin session is a cookie (admin_token, 30 days when "remember me" is checked, otherwise 1 hour).
• /api/v1/app/* is authenticated with the app_key cookie instead of an admin session.

🗂️ Project Structure

GoAccountHub/
├── main.go, frontend.go        # entry point, go:embed of GAHFrontend/dist
├── adminControllor/            # admin API handlers (admin, user, character, key, dashboard)
├── appControllor/              # API handlers for third-party apps
├── checkControllor/            # admin token check
├── middleware/                 # config/DB injection, admin auth, permission, app_key check
├── router/                     # route registration and the embedded frontend handler
├── sql/                        # database connection and queries
├── sqlTable/                   # GORM models
├── cliAction/                  # CLI commands (start / password / generate / generate-test)
├── GAHFrontend/                # Vue 3 + Vite management page
├── build.go                    # magefile: frontend / build / cross targets
└── GAHversion                  # version file

📚 Documentation

• API reference — English | 简体中文
• CLI reference — English | 简体中文

🏗️ Build & Release

GitHub Actions (.github/workflows/go.yml) runs on pushes to main only:

• test — go test ./...
• release — installs mage, then runs mage allcross: the frontend is built once, then cross compiled for windows / linux / darwin on amd64 and arm64; all six binaries are uploaded as a single GoAccountHub-<GAHversion> artifact

📄 License

MIT