# onex is a whole stack demonstrated in one repository

> onex is an MIT licensed Go project that sets out to demonstrate an enterprise microservice and cloud native stack end to end, and the interesting part is not any single service but the convention layer around it, since the repository ships directory, code, logging, error code, documentation, commit and version rules, and the Makefile is the interface to all of them.

**onexstack/onex** — 高质量、易维护、高扩展的企业级 Go 项目+ 云原生项目开发脚手架

- Repository: https://github.com/onexstack/onex
- Website: https://konglingfei.com
- Stars: 598 · Forks: 112
- Language: Go
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/onexstack-onex

## A platform for learning, and a reference layout

OneX is described as a Go language plus cloud native practical platform, and also as an enterprise grade cloud platform, built with a best practice approach. The README positions it as a project made for Go and cloud native learning, and it is one of the projects in the OneX tech stack, with a community repository for the wider set.

The name carries the intent. OneX stands for a project with complete functionality and high extensibility, and the README explains the reasoning: because the design considered future feature and architecture extension from the start, new capabilities can be added seamlessly later. For a reference project, that is a design goal rather than a slogan, since a layout that has to absorb new services later is a layout that has to be generic.

The documentation lives outside the repository, on konglingfei.com, split into a project introduction, deployment, project testing, a feature list and development documentation. The repository carries a Chinese README with English, Japanese and Korean variants, README.en.md, README.ja.md and README.ko.md, so the audience for the code is international even though the primary documentation language is Chinese.

The licence is MIT, there is a code of conduct, a CONTRIBUTING.md and a SECURITY_CONTACTS file, and the badge set is the usual round of Go tooling ones, a GoDoc badge, a Go Report Card badge, a pkg.go.dev reference badge and a build and test workflow badge.

## The four stacks the project claims to cover

The feature list organises the curriculum into four tech stacks, and the grouping is more informative than the individual items.

The software development foundations stack covers Linux, shell programming, Makefile programming and Git, which is the tooling every Go developer already uses and the part of a curriculum that is usually left implicit.

The Go development stack is the bulk of it. Web programming, and a list of application shapes: SDKs, ETL data extraction, an authentication and authorisation centre, command line tools, web services, distributed jobs, code checking and code generation. Then middleware, the HTTP, HTTPS, gRPC and WebSocket protocols, and the design and development of common functional pieces.

The cloud native stack covers Kubernetes programming, Docker practice, Kubernetes practice, cloud native deployment, declarative programming and immutable infrastructure.

The microservices stack covers distributed logging, monitoring and alerting, service orchestration, call chains, load balancing, service governance and a configuration centre.

What makes the list useful is its shape. Almost every item in the Go and microservices rows is a thing you would otherwise buy, and the interesting claim is that this project uses most of the Go ecosystem's features and implementation styles, so that a single project can be a closed loop for learning the whole stack. The components named in the dependencies, Kratos, gorm, casbin, Consul, etcd, Kitex, MinIO, gRPC and WebSocket, are the concrete evidence of that claim.

## Standards first, and the tooling that enforces them

The third stated characteristic is that standards come first, and the list of standards is explicit: directory conventions, code conventions, logging conventions, error code conventions, documentation conventions, commit conventions and version conventions.

A list of conventions is not unusual in a Chinese-language enterprise project, and in the abstract it is easy to dismiss. What makes this one concrete is that the repository contains the enforcement machinery, and the file names at the root are the inventory.

There is a .golangci.yaml for the Go linter, a .gitlint for commit message linting, a .kube-linter.yaml for Kubernetes manifests, an .air.toml for live reload during development, a .chglog/ directory for changelog generation, an .uplift.yaml for automated version bumps, a .gitlint file, a githooks/ directory, a .go-version file pinning the Go toolchain, an OWNERS file and an OWNERS_ALIASES file, and a .onexstack/ directory.

There is also a CODE_OF_CONDUCT.md, a CHANGELOG.md, a .note.md and a .todo.md. That combination, a linter for each category of rule and a hook directory, is what turns a conventions document into something a contributor cannot accidentally ignore, and it is the most transferable part of the repository.

The stated code quality goals are also specific: the project follows programming paradigms including imperative and declarative styles, adheres to clean architecture, keeps the code concise and robust, aims for high interface performance, high maintainability and high extensibility.

## The Makefile is the interface, and it is unusually well documented

The build is driven entirely by make, and the Makefile is written to be read. The default goal is help, so running make with no arguments prints the usage, and the usage block is a set of named options with descriptions.

The options that matter most are BINS, the binaries to build with a default of all of cmd, and IMAGES, the backend images to make with a default of all cmd entries starting with onex-. Both take a space separated list, so you can build one component or several. There is also DBG for generating debug symbols, DEPLYS to deploy all configured services, REGISTRY_PREFIX for the Docker registry prefix, and PLATFORMS for the multiple platforms to build, defaulting to linux_amd64 and linux_arm64.

Those options appear as environment-style variables in the usage block, and they are passed on the command line, which is the convention the README demonstrates:

```
$ make build BINS=onex-usercenter VERSION=v0.1.0
$ make image IMAGES="onex-usercenter"
```

The rules themselves are split out, with common.mk included first and then all.mk, both under scripts/make-rules, and the file starts with a comment that the build happens by default even if it is not the first target, with the all target running format, tidy, gen, add-copyright, lint, cover and build in that order.

That ordering is the interesting part. Formatting, tidying, code generation and a copyright check all run before linting and coverage, which means the definition of done in this project is a pipeline, and a contributor runs it by typing make.

## Getting it running, and the Debian 12 caveat

The installation section is three commands:

```
$ git clone https://github.com/onexstack/onex.git
$ cd onex
```

The third command is the containerised quick start, and the README attaches a strong caveat to it: the local quick setup of OneX in a container works best on a freshly installed Debian 12 Linux distribution. That is the sort of detail that only appears when the author has tested it, and it is the first thing to check before you assume the quick start will work on your distribution.

The build and image commands are the ones shown above, and the release path adds a push target, with the registry prefix option letting you point the build at your own registry. The README points at the container deployment documentation for the details.

The end-to-end usage is Kubernetes shaped. You create the sample manifest set from the manifests directory and then drive the project with its own command line tool:

```
$ kubectl create -f ${PROJ_ROOT_DIR}/manifests/sample/onex/minerset.yaml
$ onexctl --config ${ONEX_CONFIG_DIR}/onexctl.yaml minerset list
```

The presence of a minerset sample and a minerset list command tells you the project models a set of mining machines as a custom resource, and that the operator tooling is expected to be run against a live cluster rather than only in development.

## The dependency list is the architecture diagram

The go.mod file is long, and the most useful thing in it is what it says about the service framework and the supporting infrastructure.

The service framework is go-kratos at v2.8.3, with its contrib registry packages for Consul and for etcd, the gRPC framework Kitex at v0.12.1, and go-resty for HTTP calls. gorm and the casbin gorm adapter are there for persistence and for authorisation, with casbin itself at v2.103.0 along with a casbin redis watcher for policy changes. The Consul API at v1.31.1 is the service registry, and the etcd registry contrib package is the alternative.

The rest of the list is the kind of broad surface the feature list promised: gin for HTTP, gorilla websocket, gRPC with Envoy's protoc-gen-validate, MinIO's Go client for object storage, google wire for compile time dependency injection, golang-jwt, google mock for tests, minio, ristretto as a cache, a worker pool, a table writer for CLI output, blang semver, fatih color, a survey library for interactive prompts, and a lancet utility library.

Two entries deserve attention because they are unusual in a dependency list. The module requires github.com/armon/go-socks5, a SOCKS5 proxy implementation, which suggests the project supports routing traffic through a proxy as a first class concern. And it requires github.com/onexstack/onexstack itself at a placeholder version, which is the internal sibling package of the same organisation.

The module targets Go 1.26.0, and the .go-version file in the repository pins the toolchain, so the build is reproducible in the same sense the MSL regression suite is not.

## Where onex is the wrong tool

The first case is a team that wants a framework. The dependency list makes it obvious that this project is an application, not a library: the services are named onex-usercenter, onex-gateway and onex-miner-controller, they live under cmd/, and they talk to each other. Importing onex into another project is not a thing this repository is set up for, and the thing worth taking from it is the layout and the rules rather than the services.

The second case is a team that already has a framework. A Go microservice team that has chosen Kratos, or gRPC and protobuf with a specific code generation pipeline, or an internal platform with its own conventions, gets nothing from a second opinion expressed in a different set of conventions. The Makefile, the lint configuration and the hook directory are all tuned to this repository.

The third case is a team that cannot maintain a repository this size. The tree contains api/, build/, cmd/, configs/, docs/, examples/, internal/, manifests/, pkg/, scripts/, staging/, test/, third_party/ and tools/, plus a githooks/ directory and a set of lint configurations. Adopting all of that means adopting the maintenance that goes with it, and one project means one author, with a single email address given for feedback.

The alternative for a learner is to pick one of the frameworks and build something small and real with it. That path teaches less about enterprise conventions and more about the framework, which is usually the better trade. What onex offers is the opposite: a working example of how a large, convention driven Go service tree is put together, in one place, with the enforcement attached, and with a documentation site that walks through deployment and testing.

## Conclusion

onex fits a Go developer who wants to see what a convention driven enterprise layout looks like in practice, since the rules are enforced by tools in the repository rather than described in prose, and it fits a team looking for a reference before writing its own service scaffolding. It does not fit a team that wants a framework to import, since this is a demonstration project rather than a library, and its own documentation is hosted on a separate site rather than in the repository. Before adopting any part of it, read the Makefile usage options and the build rules under scripts/make-rules, and copy the conventions rather than the services, since the services exist to demonstrate the conventions.

## FAQ

### What is the onex project?

It is an MIT licensed Go project that presents itself as a Go plus cloud native practical platform and an enterprise grade cloud platform, covering foundations, Go development, cloud native and microservices stacks, with documentation hosted at konglingfei.com/onex.

### How do I build and install onex?

Clone the repository, cd into it, and use the make targets: make build to compile the binaries under cmd, make build BINS=onex-usercenter to build one component, make image and make push for the Docker images. The containerised quick start is make docker-install, which the README says works best on a freshly installed Debian 12.

### What conventions does the onex project enforce?

Directory, code, logging, error code, documentation, commit and version conventions, and the repository carries the tooling for them, including a golangci configuration, a gitlint file, a kube-linter configuration, a changelog directory, an uplift configuration for version bumps, a hooks directory and an OWNERS file.

### Which framework and infrastructure does onex use?

The go.mod file requires go-kratos v2.8.3 with its Consul and etcd registry packages, Kitex v0.12.1, gorm with a casbin adapter, casbin v2.103.0, the Consul API, gin, gorilla websocket, MinIO's Go client, google wire and resty, on Go 1.26.0.

### How do you use onex once it is running?

The usage is Kubernetes shaped: create the sample manifest set with kubectl create -f on the minerset sample, then drive the project with its own command line tool, for example onexctl --config onexctl.yaml minerset list.

## Sources

- [Issues](https://github.com/onexstack/onex/issues)
- [License: MIT](https://github.com/onexstack/onex/blob/master/LICENSE)
- [onexstack/onex on GitHub](https://github.com/onexstack/onex)
- [Project website](https://konglingfei.com)
- [README](https://github.com/onexstack/onex/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/onexstack-onex