Upload 1793 files

.air.toml

@@ -0,0 +1,47 @@
+# Config file for [Air](https://github.com/cosmtrek/air) in TOML format
+
+# Working directory
+# . or absolute path, please note that the directories following must be under root.
+root = "."
+tmp_dir = "tmp"
+
+[build]
+# Just plain old shell command. You could use `make` as well.
+cmd = "go build -o ./tmp/axonhub cmd/axonhub/main.go"
+# Binary file yields from `cmd`.
+bin = "./tmp/axonhub"
+# Customize binary.
+full_bin = "APP_USER=air ./tmp/axonhub"
+# Watch these filename extensions.
+include_ext = ["go","yml"]
+# Ignore these filename extensions or directories.
+exclude_dir = ["assets", "tmp", "vendor", "frontend", "integration_test", "website", "scripts", "openspec", "llm/tools","tools" ,"examples"]
+# Watch these directories if you specified.
+include_dir = []
+# Exclude files.
+exclude_file = []
+# This log file places in your tmp_dir.
+log = "air.log"
+# It's not necessary to trigger build each time file changes if it's too frequent.
+delay = 10000 # ms
+# Stop running old binary when build errors occur.
+stop_on_error = true
+# Send Interrupt signal before killing process (windows does not support this feature)
+send_interrupt = false
+# Delay after sending Interrupt signal
+kill_delay = 1000 # ms
+
+[log]
+# Show log time
+time = false
+
+[color]
+# Customize each part's color. If no color found, use the raw app log.
+main = "magenta"
+watcher = "cyan"
+build = "yellow"
+runner = "green"
+
+[misc]
+# Delete tmp directory on exit
+clean_on_exit = true

.dockerignore

@@ -0,0 +1,19 @@
+.git
+.gitignore
+.dockerignore
+node_modules
+frontend/node_modules
+frontend/dist
+.axonhub
+axonhub
+axonhub.db
+.DS_Store
+*.log
+coverage
+dist
+build
+.vscode
+.idea
+.env
+.env.local
+.env.*.local

.gitattributes

@@ -33,3 +33,13 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-channels.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-dashboard.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-model-price.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-models.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-profiles.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-requests.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-system.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-trace.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-usage-logs.png filter=lfs diff=lfs merge=lfs -text
+docs/screenshots/axonhub-users.png filter=lfs diff=lfs merge=lfs -text

.golangci.yml

@@ -0,0 +1,393 @@
+# This file contains all available configuration options
+# with their default values.
+
+version: "2"
+# options for analysis running
+run:
+  # default concurrency is a available CPU number
+  concurrency: 4
+
+  # timeout for analysis, e.g. 30s, 5m, default is 1m
+  timeout: 10m
+
+  # exit code when at least one issue was found, default is 1
+  issues-exit-code: 1
+
+  # include test files or not, default is true
+  tests: true
+
+  # list of build tags, all linters use it. Default is empty list.
+  build-tags: []
+
+
+linters:
+  default: all
+  disable:
+    - prealloc
+    - errchkjson
+    - contextcheck
+    - rowserrcheck
+    - sqlclosecheck
+    - wastedassign
+    - forbidigo
+    - gocritic
+    - revive
+    - nonamedreturns
+    - wrapcheck
+    - varnamelen
+    - paralleltest
+    - nlreturn
+    - testpackage
+    - gochecknoglobals
+    - wsl
+    - ireturn
+    - godox
+    - cyclop
+    - whitespace
+    - nolintlint
+    - unused
+    - depguard
+    - lll
+    - exhaustruct
+    - gochecknoinits
+    - dupl
+    - tagalign
+    - funlen
+    - gomoddirectives
+    - nestif
+    - testableexamples
+    - gocyclo
+    - gosmopolitan
+    - perfsprint
+    - inamedparam
+    - interfacebloat
+    - unparam
+    - mnd
+    - recvcheck
+    - tagliatelle
+    - goconst
+    - gocognit
+    - err113
+    - funcorder
+    - noinlineerr
+    - nilnil
+    - thelper
+    - dogsled
+    - unqueryvet
+    - predeclared
+    
+
+  # all available settings of specific linters
+  settings:
+    dogsled:
+      # checks assignments with too many blank identifiers; default is 2
+      max-blank-identifiers: 2
+    dupl:
+      # tokens count to trigger issue, 150 by default
+      threshold: 100
+    errcheck:
+      # report about not checking of errors in type assertions: `a := b.(MyStruct)`;
+      # default is false: such cases aren't reported by default.
+      check-type-assertions: false
+
+      # report about assignment of errors to blank identifier: `num, _ := strconv.Atoi(numStr)`;
+      # default is false: such cases aren't reported by default.
+      check-blank: false
+
+    funlen:
+      lines: 60
+      statements: 40
+    gocognit:
+      # minimal code complexity to report, 30 by default (but we recommend 10-20)
+      min-complexity: 20
+    goconst:
+      # minimal length of string constant, 3 by default
+      min-len: 3
+      # minimal occurrences count to trigger, 3 by default
+      min-occurrences: 3
+    gocritic:
+      # Which checks should be enabled; can't be combined with 'disabled-checks';
+      # See https://go-critic.github.io/overview#checks-overview
+      # To check which checks are enabled run `GL_DEBUG=gocritic golangci-lint run`
+      # By default list of stable checks is used.
+      enabled-checks: []
+
+      # Enable multiple checks by tags, run `GL_DEBUG=gocritic golangci-lint run` to see all tags and checks.
+      # Empty list by default. See https://github.com/go-critic/go-critic#usage -> section "Tags".
+      enabled-tags:
+        - performance
+
+      settings: # settings passed to gocritic
+        captLocal: # must be valid enabled check name
+          paramsOnly: true
+        rangeValCopy:
+          sizeThreshold: 32
+    gocyclo:
+      # minimal code complexity to report, 30 by default (but we recommend 10-20)
+      min-complexity: 10
+    godox:
+      # report any comments starting with keywords, this is useful for TODO or FIXME comments that
+      # might be left in the code accidentally and should be resolved before merging
+      keywords: [] # default keywords are TODO, BUG, and FIXME, these can be overwritten by this setting
+    govet:
+      # settings per analyzer
+      settings:
+        printf: # analyzer name, run `go tool vet help` to see all analyzers
+          funcs: # run `go tool vet help printf` to see available settings for `printf` analyzer
+            - (github.com/golangci/golangci-lint/pkg/logutils.Log).Infof
+            - (github.com/golangci/golangci-lint/pkg/logutils.Log).Warnf
+            - (github.com/golangci/golangci-lint/pkg/logutils.Log).Errorf
+            - (github.com/golangci/golangci-lint/pkg/logutils.Log).Fatalf
+
+      # enable or disable analyzers by name
+      enable:
+        - atomicalign
+      disable:
+        - shadow
+      disable-all: false
+
+    lll:
+      # max line length, lines longer will be reported. Default is 120.
+      # '\t' is counted as 1 character by default, and can be changed with the tab-width option
+      line-length: 180
+      # tab width in spaces. Default to 1.
+      tab-width: 1
+    misspell:
+      # Correct spellings using locale preferences for US or UK.
+      # Default is to use a neutral variety of English.
+      # Setting locale to US will correct the British spelling of 'colour' to 'color'.
+      locale: US
+    nakedret:
+      # make an issue if func has more lines of code than this setting and it has naked returns; default is 30
+      max-func-lines: 30
+    prealloc:
+      # XXX: we don't recommend using this linter before doing performance profiling.
+      # For most programs usage of prealloc will be a premature optimization.
+
+      # Report preallocation suggestions only on simple loops that have no returns/breaks/continues/gotos in them.
+      # True by default.
+      simple: true
+      range-loops: true # Report preallocation suggestions on range loops, true by default
+      for-loops: false # Report preallocation suggestions on for loops, false by default
+    unparam:
+      # Inspect exported functions, default is false. Set to true if no external program/library imports your code.
+      # XXX: if you enable this setting, unparam will report a lot of false-positives in text editors:
+      # if it's called for subdir of a project it can't find external interfaces. All text editor integrations
+      # with golangci-lint call it on a directory with the changed file.
+      check-exported: false
+    whitespace:
+      multi-if: false # Enforces newlines (or comments) after every multi-line if statement
+      multi-func: false # Enforces newlines (or comments) after every multi-line function signature
+    wsl:
+      # If true append is only allowed to be cuddled if appending value is
+      # matching variables, fields or types on line above. Default is true.
+      strict-append: true
+      # Allow calls and assignments to be cuddled as long as the lines have any
+      # matching variables, fields or types. Default is true.
+      allow-assign-and-call: true
+      # Allow multiline assignments to be cuddled. Default is true.
+      allow-multiline-assign: true
+      # Allow declarations (var) to be cuddled.
+      allow-cuddle-declarations: true
+      # Allow trailing comments in ending of blocks
+      allow-trailing-comment: false
+      # Force newlines in end of case at this limit (0 = never).
+      force-case-trailing-whitespace: 0
+
+  
+  exclusions:
+    # Exclude all linters from running on ent files.
+    paths:
+      - internal/ent
+    # Excluding configuration per-path, per-linter, per-text and per-source
+    rules:
+      # Exclude some linters from running on tools files.
+      - path: tools/
+        linters:
+          - gosec
+          - errcheck
+      # Exclude some linters from running on tests files.
+      - path: _test\.go$
+        linters:
+          - noctx
+          - sqlclosecheck
+          - gocyclo
+          - errcheck
+          - dupl
+          - gosec
+          - unused
+          - deadcode
+          - exhaustruct
+          - funlen
+          - maintidx
+          - cyclop
+          - gocognit
+          - unparam
+          - containedctx
+          - goconst
+          - ineffassign
+          - staticcheck
+          - bodyclose
+          - forcetypeassert
+          - predeclared
+          - testifylint
+          - musttag
+          - dupword
+          - intrange
+          - govet
+          - errname
+          - noinlineerr
+          - nilnil
+          - exhaustive
+
+      - path: _mock\.go$
+        linters:
+          - gofmt
+
+      # Exclude some staticcheck messages
+      - linters:
+          - staticcheck
+        text: "SA9003:"
+
+      - linters:
+          - staticcheck
+        text: "SA1019:"
+
+      - linters:
+          - staticcheck
+        text: "SA4009:"
+
+      - linters:
+          - staticcheck
+        text: "ST1001:"
+
+      - linters:
+          - staticcheck
+        text: "QF1008:"
+
+      - linters:
+          - staticcheck
+        text: "ST1005:"
+
+      - linters:
+          - stylecheck
+        text: "ST1001:"
+
+      - linters:
+          - stylecheck
+        text: "ST1003:"
+
+      - linters:
+          - stylecheck
+        text: "ST1006:"
+
+      - linters:
+          - stylecheck
+        text: "ST1016:"
+
+      # Exclude lll issues for long lines with go:generate
+      - linters:
+          - lll
+        source: "^//go:generate "
+
+formatters:
+  # Enable specific formatter.
+  # Default: [] (uses standard Go formatting)
+  enable:
+    - gci
+    - gofmt
+    - gofumpt
+    - goimports
+    # - golines
+  settings:
+    gci:
+      # Section configuration to compare against.
+      # Section names are case-insensitive and may contain parameters in ().
+      # The default order of sections is `standard > default > custom > blank > dot > alias > localmodule`.
+      # If `custom-order` is `true`, it follows the order of `sections` option.
+      # Default: ["standard", "default"]
+      sections:
+        - standard # Standard section: captures all standard packages.
+        - default # Default section: contains all imports that could not be matched to another section type.
+        - blank # Blank section: contains all blank imports. This section is not present unless explicitly enabled.
+        - dot # Dot section: contains all dot imports. This section is not present unless explicitly enabled.
+        - alias # Alias section: contains all alias imports. This section is not present unless explicitly enabled.
+        - localmodule # Local module section: contains all local packages. This section is not present unless explicitly enabled.
+      # Checks that no inline comments are present.
+      # Default: false
+      no-inline-comments: false
+      # Checks that no prefix comments (comment lines above an import) are present.
+      # Default: false
+      no-prefix-comments: false
+      # Enable custom order of sections.
+      # If `true`, make the section order the same as the order of `sections`.
+      # Default: false
+      custom-order: true
+      # Drops lexical ordering for custom sections.
+      # Default: false
+      no-lex-order: true
+
+    golines:
+      # Target maximum line length.
+      # Default: 100
+      max-len: 180
+      # Length of a tabulation.
+      # Default: 4
+      tab-len: 4
+      # Shorten single-line comments.
+      # Default: false
+      shorten-comments: true
+      # Default: true
+      reformat-tags: false
+      # Split chained methods on the dots as opposed to the arguments.
+      # Default: true
+      chain-split-dots: false
+    
+    goimports:
+      # Local prefixes to use with "goimports -local".
+      # Default: []
+      local-prefixes:
+        - "github.com/looplj/axonhub"
+
+  exclusions:
+    # Mode of the generated files analysis.
+    #
+    # - `strict`: sources are excluded by strictly following the Go generated file convention.
+    #    Source files that have lines matching only the following regular expression will be excluded: `^// Code generated .* DO NOT EDIT\.$`
+    #    This line must appear before the first non-comment, non-blank text in the file.
+    #    https://go.dev/s/generatedcode
+    # - `lax`: sources are excluded if they contain lines like `autogenerated file`, `code generated`, `do not edit`, etc.
+    # - `disable`: disable the generated files exclusion.
+    #
+    # Default: lax
+    generated: lax
+    # Which file paths to exclude.
+    # This option is ignored when using `--stdin` as the path is unknown.
+    # Default: []
+    paths:
+      - ".resolvers.go"
+      - "axonhub.resolvers.go"
+      - "ent.resolvers.go"
+      - "internal/ent"
+      - "internal/server/gql/ent.resolvers.go"
+  
+
+issues:
+  # make issues output unique by line, default is true
+  uniq-by-line: true
+
+  max-issues-per-linter: 0
+
+  # Maximum count of issues with the same text. Set to 0 to disable. Default is 3.
+  max-same-issues: 0
+
+  # Show only new issues: if there are unstaged changes or untracked files,
+  # only those changes are analyzed, else only changes in HEAD~ are analyzed.
+  # It's a super-useful option for integration of golangci-lint into existing
+  # large codebase. It's not practical to fix all existing issues at the moment
+  # of integration: much better don't allow issues in new code.
+  # Default is false.
+  new: true
+
+  # Auto-fix enabled issues. Default is false.
+  fix: true

.goreleaser.yml

@@ -0,0 +1,89 @@
+version: 2
+
+project_name: axonhub
+
+dist: .builds
+
+before:
+  hooks:
+    - /bin/sh -c 'cd deploy && chmod +x *.sh'
+    - make build-frontend
+    - go mod tidy
+
+builds:
+  - id: build
+    main: ./cmd/axonhub
+    binary: axonhub
+    flags:
+      - -tags=nomsgpack
+    ldflags:
+      - -s -w -X github.com/looplj/axonhub/internal/build.Version={{ .Tag }}
+      - -s -w -X github.com/looplj/axonhub/internal/build.Commit={{ .Commit }}
+      - -s -w -X github.com/looplj/axonhub/internal/build.BuildTime={{ .Date }}
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - windows
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+      - loong64
+    goarm:
+      - 7
+    ignore:
+      - goos: windows
+        goarch: arm
+      - goos: windows
+        goarch: s390x
+      - goos: windows
+        goarch: loong64
+      - goos: darwin
+        goarch: arm
+      - goos: darwin
+        goarch: s390x
+      - goos: darwin
+        goarch: loong64
+
+release:
+  draft: true
+
+archives:
+  - id: archive
+    ids: [build]
+    formats: [zip]
+    files:
+      - LICENSE
+      - CHANGELOG.md
+      - src: deploy/install.sh
+        dst: install.sh
+      - src: deploy/start.sh
+        dst: start.sh
+      - src: deploy/stop.sh
+        dst: stop.sh
+      - src: deploy/install.ps1
+        dst: install.ps1
+      - src: deploy/start.ps1
+        dst: start.ps1
+      - src: deploy/stop.ps1
+        dst: stop.ps1
+      - src: deploy/install.bat
+        dst: install.bat
+      - src: deploy/start.bat
+        dst: start.bat
+      - src: deploy/stop.bat
+        dst: stop.bat
+
+checksum:
+  name_template: 'checksums.txt'
+
+snapshot:
+  version_template: '{{ incpatch .Version }}-snapshot'
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - '^examples:'
+      - '^ui:'

.mockery.yml

@@ -0,0 +1,17 @@
+all: false
+dir: '{{.InterfaceDir}}'
+filename: '{{.InterfaceName|snakecase}}.mock.gen.go'
+force-file-write: true
+formatter: goimports
+log-level: info
+structname: '{{.Mock}}{{.InterfaceName}}'
+pkgname: '{{.SrcPackageName}}'
+recursive: false
+require-template-schema-exists: true
+template: testify
+template-schema: '{{.Template}}.schema.json'
+packages:
+  github.com/looplj/axonhub/llm/pipeline:
+    config:
+    interfaces:
+      Executor:

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: 'https://github.com/golangci/golangci-lint'
+    rev: v2.8.0
+    hooks:
+      - id: golangci-lint
+        entry: golangci-lint run -vvv
+
+  - repo: local
+    hooks:
+      - id: run-go-test
+        name: Run go test
+        entry: bash -c 'go test ./... --short'
+        language: system
+        types: [go]
+        pass_filenames: false
+
+  - repo: https://github.com/dnephin/pre-commit-golang
+    rev: v0.5.1
+    hooks:
+      #      - id: go-build
+      - id: go-mod-tidy
+

AGENTS.md

@@ -0,0 +1,3 @@
+# Repository Guidelines
+
+@CLAUDE.md read and follow its instructions.

CHANGELOG.md

@@ -0,0 +1,20 @@
+v0.4.0
+
+- Introduced thread-aware tracing with zero-SDK integration and configurable trace headers
+- Added trace visualization interface for following end-to-end conversations
+- Added configurable data storage policies to keep or trim trace payloads based on compliance needs
+
+v0.3.0
+
+- Launched project workspace management with per-project API keys and dashboards
+- Improved project-scoped permissions and usage insights
+
+v0.2.0
+
+- Added multimodal image generation via chat completions and image_generation tools
+- Documented provider support and sample usage for image workflows
+
+v0.1.1
+
+- Add OpenRouter outbound transformer
+- Support Google Gemini OpenAI compatible API

CLAUDE.md

@@ -0,0 +1,428 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+AxonHub is an all-in-one AI development platform that serves as a unified API gateway for multiple AI providers. It provides OpenAI and Anthropic-compatible API interfaces with automatic request transformation, enabling seamless communication between clients and various AI providers through a sophisticated bidirectional data transformation pipeline.
+
+### Core Architecture
+- **Transformation Pipeline**: Bidirectional data transformation between clients and AI providers
+- **Unified API Layer**: OpenAI/Anthropic-compatible interfaces with automatic translation
+- **Channel Management**: Multi-provider support with configurable channels
+- **Thread-aware Tracing**: Request tracing with thread linking capabilities
+- **Permission System**: RBAC with fine-grained access control
+- **System Management**: Web-based configuration interface
+
+## Development Commands
+
+### Backend (Go)
+```bash
+# Run the main server
+go run cmd/axonhub/main.go
+
+# Generate GraphQL and Ent code (run after schema changes)
+make generate
+
+# Run tests
+go test ./...
+
+# Run linting
+golangci-lint run
+
+# Build the application
+make build-backend
+
+# Use air for hot reload (development) - server auto-restarts on changes
+air
+```
+
+### Frontend (React)
+```bash
+# Navigate to frontend directory
+cd frontend
+
+# Install dependencies
+pnpm install
+
+# Start development server (port 5173) - already configured with backend proxy
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run linting
+pnpm lint
+
+# Format code
+pnpm format
+
+# Check for unused dependencies
+pnpm knip
+
+# Tests (Playwright)
+pnpm test:e2e            # run E2E suite via scripts/e2e
+pnpm test:e2e:headed     # headed browser mode
+pnpm test:e2e:ui         # Playwright UI runner
+pnpm test:e2e:debug      # debug mode
+pnpm test:e2e:report     # open last HTML report
+pnpm test:ui             # Playwright UI (direct)
+pnpm test:ui:headed      # Playwright headed (direct)
+```
+
+### Make Commands
+```bash
+# Generate GraphQL and Ent code
+make generate
+
+# Build backend only
+make build-backend
+
+# Build frontend only
+make build-frontend
+
+# Build both frontend and backend
+make build
+
+# Cleanup test database
+make cleanup-db
+
+# E2E Testing
+make e2e-test                    # Run full E2E test suite
+make e2e-backend-start          # Start E2E backend service
+make e2e-backend-stop           # Stop E2E backend service
+make e2e-backend-status         # Check E2E backend status
+make e2e-backend-restart        # Restart E2E backend service
+make e2e-backend-clean          # Clean up E2E test files
+
+# Migration Testing
+make migration-test TAG=v0.1.0  # Test migration from specific tag
+make migration-test-all         # Test migration for all recent versions
+make migration-test-all-dbs TAG=v0.1.0  # Test migration across all DB types
+
+# Data Syncing
+make sync-faq                   # Sync FAQ from GitHub issues
+make sync-models                # Sync model developers data
+
+# Utilities
+make filter-logs                # Filter and analyze load balance logs
+```
+
+## Architecture Overview
+
+### Technology Stack
+- **Backend**: Go 1.25.3+ with Gin HTTP framework, Ent ORM, gqlgen GraphQL, FX dependency injection
+- **Frontend**: React 19 with TypeScript, TanStack Router, TanStack Query, Zustand, Tailwind CSS
+- **Database**: SQLite (development), PostgreSQL/MySQL/TiDB (production)
+- **Authentication**: JWT with role-based access control
+
+### Backend Structure
+- **Server Layer** (`internal/server/`): HTTP server and route handling with Gin
+- **Business Logic** (`internal/server/biz/`): Core business logic and services
+- **API Layer** (`internal/server/api/`): REST and GraphQL API handlers
+- **Database** (`internal/ent/`): Ent ORM for database operations with SQLite
+- **LLM Integration** (`internal/llm/`): AI provider transformers and pipeline processing
+- **Context Management** (`internal/contexts/`): Context handling utilities
+- **Utilities** (`internal/pkg/`): Shared utilities (HTTP client, streams, errors, JSON)
+- **Auth & Scopes** (`internal/scopes/`): Permission system with role-based access control
+
+### Frontend Structure
+- **TanStack Router**: File-based routing in `frontend/src/routes/`
+- **TanStack Query**: Data fetching and caching with GraphQL
+- **TanStack Table**: Data tables with pagination/filtering
+- **GraphQL**: API communication via `frontend/src/gql/`
+- **Shadcn/ui**: Component library with Tailwind CSS
+- **Zustand**: State management in `frontend/src/stores/`
+- **AI SDK**: Integration for enhanced AI capabilities
+- **Feature-based Organization**: Components organized by feature in `frontend/src/features/`
+- **Shared Components**: Reusable components in `frontend/src/components/`
+- **Custom Hooks**: Shared hooks in `frontend/src/hooks/`
+- **Internationalization**: i18n support in `frontend/src/locales/` (en.json, zh.json)
+- **Utilities**: Shared utilities in `frontend/src/utils/`
+
+### Key Components
+
+#### LLM Transformer System
+- **Pipeline Architecture**: Enhanced request processing with retry capabilities
+- **Persistent Transformers**: `PersistentInboundTransformer` and `PersistentOutboundTransformer`
+- **Stream Processing**: Enhanced SSE support with chunk aggregation
+- **Supported Providers**: OpenAI, Anthropic, DeepSeek, AI SDK
+- **Auto-save**: Configurable persistence of chat requests and responses
+- **Load Balancing**: Round-robin and failover strategies
+
+#### Database Schema
+- **Users**: Authentication and role management with soft delete
+- **Roles**: Permission groups with scope-based access
+- **Channels**: AI provider configurations
+- **API Keys**: Authentication tokens
+- **Requests**: Request logging and execution tracking
+- **Systems**: System-wide configuration (storeChunks, etc.)
+- **Soft Delete**: Data safety across all entities
+
+#### Permission System
+- **Enhanced Scopes**: read_channels, write_channels, read_users, read_settings, write_settings
+- **Owner scope**: Full system access
+- **Role-based access control**: Users can have multiple roles
+- **Ent privacy policies**: Database-level permission enforcement
+- **Granular permissions**: Fine-grained access control
+
+#### System Management
+- **Web Interface**: Complete system settings management
+- **Configuration Options**: Controllable persistence and system behavior
+- **Real-time Updates**: Live configuration changes
+- **GraphQL API**: System configuration endpoints
+
+
+### Development Workflow
+
+#### General Notes
+- All summary files should be stored in `.windsurf/summary` directory if available
+
+#### Backend Development
+1. **Code Changes**: Modify Go code in `internal/` directory
+2. **Schema Changes**: If modifying Ent schemas (`internal/ent/schema/`), run `make generate`
+   - When changing any Ent schema or GraphQL schema, run `make generate` to regenerate models and resolvers
+   - The `make generate` command automatically enters the gql directory and runs go generate
+3. **GraphQL Changes**: If modifying GraphQL schemas (`internal/server/gql/`), run `make generate`
+4. **Hot Reload**: Use `air` for automatic server restart on changes (configured in `.air.toml`)
+   - **CRITICAL**: The server in development is managed by air - it will rebuild and start when code changes, so DO NOT restart manually
+   - Air watches `.go` and `.yml` files
+   - Excludes directories: `frontend`, `integration_test`, `scripts`, `tools`, `examples`
+   - Builds to `./tmp/axonhub`
+
+   **Dev vs prod builds**
+   - Dev hot-reload uses Air (`.air.toml`) and builds to `./tmp/axonhub`.
+   - Production build uses `make build-backend` and outputs `./axonhub`.
+
+5. **Building**: Use `make build-backend` to build the server for production deployment
+6. **Testing**: Run `go test ./...` for unit tests
+7. **Linting**: Run `golangci-lint run` before committing
+
+#### Frontend Development
+1. **Start Dev Server**: Run `pnpm dev` in `frontend/` directory (port 5173)
+   - **CRITICAL**: DO NOT restart the development server - it's already started and managed
+2. **Proxy Configuration**: Frontend proxies API requests to backend on port 8090
+3. **Code Changes**: Modify React components in `frontend/src/`
+4. **Internationalization**:
+   - **REQUIRED**: MUST ADD i18n key in the `frontend/src/locales/*.json` files if creating a new key in the code
+   - **REQUIRED**: MUST KEEP THE KEY IN THE CODE AND JSON FILE THE SAME
+   - Support both English and Chinese translations (`en.json` and `zh.json`)
+   - Add i18n keys to both `frontend/src/locales/en.json` and `frontend/src/locales/zh.json`
+5. **Testing**: Use `pnpm test:e2e` for E2E tests or `pnpm test:ui` for Playwright UI tests
+6. **Linting**: Run `pnpm lint` before committing
+
+**Additional Frontend Development Rules:**
+- Use `pnpm` as the package manager exclusively
+- Use GraphQL input to filter data instead of filtering in the frontend
+- Search filters must use debounce to avoid too many requests
+- Add sidebar data and route when adding new feature pages
+- Use `extractNumberID` to extract int id from the GUID
+- Follow component organization in `frontend/src/features/`
+
+#### Database Development
+1. **Schema Changes**: Modify Ent schemas in `internal/ent/schema/`
+2. **Code Generation**: Run `make generate` to regenerate Ent code
+3. **Migrations**: Auto-applied on server start
+4. **Testing**: Use `enttest.NewEntClient(t, "sqlite3", "file:ent?mode=memory&_fk=0")` for isolated tests
+
+#### Integration Testing
+1. **E2E Tests**: Run `make e2e-test` for full integration test suite
+2. **Migration Tests**: Run `make migration-test TAG=v0.1.0` to test database migrations
+3. **Cross-DB Tests**: Run `make migration-test-all-dbs TAG=v0.1.0` for multi-database migration testing
+
+## Important Files
+
+### Backend
+- `cmd/axonhub/main.go`: Application entry point
+- `internal/server/server.go`: HTTP server configuration
+- `internal/llm/pipeline/`: Pipeline processing architecture
+- `internal/ent/schema/`: Database schema definitions
+- `internal/pkg/`: Shared utilities and helpers
+- `conf/conf.go`: Configuration loading and validation
+- `internal/server/gql/`: GraphQL schema and resolvers
+
+### Frontend
+- `frontend/src/app/`: React Router v7 app directory
+- `frontend/src/features/`: Feature-based component organization
+- `frontend/src/features/system/`: System management interface
+- `frontend/src/locales/`: Internationalization files (en.json, zh.json)
+
+### Configuration & Documentation
+- `config.yml` / `config.example.yml`: Main configuration files
+- `AGENTS.md`: Repository guidelines for contributors
+- `README.md` / `README.zh-CN.md`: Project documentation
+- `docs/`: Detailed documentation and architecture diagrams
+
+## Key Development Patterns
+
+### Adding a New AI Provider Channel
+When introducing a new provider channel, keep backend and frontend changes aligned:
+
+1. **Extend the channel enum in the Ent schema** – add the provider key to the `field.Enum("type")` list in `internal/ent/schema/channel.go` and regenerate Ent artifacts
+2. **Wire the outbound transformer** – update the switch in `ChannelService.buildChannel` to construct the correct outbound transformer for the new enum
+3. **Sync the frontend schema** – update:
+   - Zod schema in `frontend/src/features/channels/data/schema.ts`
+   - Channel configuration in `frontend/src/features/channels/data/constants.ts`
+   - Internationalization in `frontend/src/locales/en.json` and `frontend/src/locales/zh.json`
+
+### Database Schema Changes
+- Always run `make generate` after modifying Ent schemas
+- Use `enttest.NewEntClient(t, "sqlite3", "file:ent?mode=memory&_fk=0")` for testing
+- Follow soft delete patterns across all entities
+
+### Go Development Patterns
+- **REQUIRED**: USE `github.com/samber/lo` package to handle collection, slice, map, ptr, etc.
+- Follow dependency injection patterns using FX framework
+- Use structured logging with zap
+- Implement proper context propagation
+- **Key Dependencies**:
+  - `entgo.io/ent` - ORM framework with code generation
+  - `github.com/99designs/gqlgen` - GraphQL code generation
+  - `github.com/gin-gonic/gin` - HTTP framework
+  - `go.uber.org/fx` - Dependency injection
+  - `github.com/google/uuid` - UUID generation
+  - `github.com/redis/go-redis/v9` - Redis client
+  - `github.com/jackc/pgx/v5` - PostgreSQL driver
+  - `github.com/go-sql-driver/mysql` - MySQL driver
+
+### Biz Service Rules
+- **REQUIRED**: Ensure the dependency service not be nil, the logic code should not check the service is nil.
+- **REQUIRED**: Dependency services are guaranteed initialized; business logic must not add nil checks.
+
+### Error Handling
+- **REQUIRED**: Always handle errors using the unified error response format from `internal/pkg/errors`
+- Implement proper error wrapping with context
+- Follow middleware-based error recovery patterns
+
+### GraphQL Development
+- **Method Signatures/New Fields**: Resolver method signatures and new field definitions should always be generated by modifying `*.graphql` schema files and running `make generate`
+- **Implementation Content**: The implementation body of existing resolver methods can be manually modified
+- Run `make generate` from the project root after schema changes
+- Use GraphQL input filtering instead of frontend filtering for data queries
+
+#### Adding New GraphQL Types
+When adding new types or inputs to the GraphQL schema, you need to:
+
+1. **Add the type/input definition** in the appropriate `.graphql` file in `internal/server/gql/`
+2. **Add type mapping in `gqlgen.yml`** under the `models:` section - map the GraphQL type to the Go type:
+   ```yaml
+   MyNewType:
+     model:
+       - github.com/looplj/axonhub/internal/package.MyType
+   MyNewInput:
+     model:
+       - github.com/looplj/axonhub/internal/package.MyInput
+   ```
+3. **Run `make generate`** to regenerate the code
+4. **Implement the resolver** in the appropriate `*_resolvers.go` file
+
+## Quality gates (match CI / pre-commit)
+
+Backend:
+- `go test -v --short ./...`
+- `golangci-lint run`
+
+Pre-commit hooks (see `.pre-commit-config.yaml`) also run:
+- `go mod tidy`
+
+## Testing
+
+### Backend Testing
+- **Unit Tests**: Go unit tests with testify
+- **Integration Tests**: Database integration tests with in-memory SQLite
+- **Test Database**: Use `enttest.NewEntClient(t, "sqlite3", "file:ent?mode=memory&_fk=0")` for isolated tests
+- **Code Quality**: `golangci-lint run` for Go linting
+- **Error Handling**: Use unified error format from `internal/pkg/errors`
+
+### Frontend Testing
+- **E2E Tests**: Playwright E2E tests with UI and headed modes
+- **Test Commands**:
+  - `pnpm test:e2e` - Run full E2E test suite
+  - `pnpm test:e2e:headed` - Run E2E tests in headed mode
+  - `pnpm test:e2e:ui` - Run E2E tests in UI mode
+  - `pnpm test:e2e:debug` - Run E2E tests in debug mode
+  - `pnpm test:ui` - Run Playwright tests in UI mode
+  - `pnpm test:ui:headed` - Run Playwright tests in headed mode
+- **Code Quality**: `pnpm lint` for TypeScript/ESLint checking
+- **Test Credentials**: Frontend testing uses `my@example.com` / `pwd123456`
+
+### Integration Testing
+- **E2E Test Suite**: Use `make e2e-test` or `bash ./scripts/e2e/e2e-test.sh` for full integration tests
+- **Migration Testing**: Use `make migration-test TAG=v0.1.0` to test database migrations
+- **Cross-DB Testing**: Use `make migration-test-all-dbs TAG=v0.1.0` to test migrations across all supported databases
+- **Test Cleanup**: Use `make cleanup-db` to remove playwright test data from database
+
+## Key Features in Development
+- Enhanced transformer stream aggregation
+- Configurable persistence behavior
+- System options for controlling data storage
+- Improved error handling and recovery mechanisms
+- Stream closing when client disconnects
+- Real-time request tracing and monitoring
+
+
+## Configuration
+
+### Environment Setup
+- Uses SQLite database (axonhub.db) by default
+- Configuration loaded from `conf/conf.go` with YAML and env var support
+- Logging with structured JSON output using zap
+- FX dependency injection framework
+- Go version: 1.25.3+
+- Frontend development server: port 5173 (proxies to backend)
+- Backend API: port 8090
+
+### Database Support
+- **Development**: SQLite (default, auto-migration)
+- **Production**: PostgreSQL 15+, MySQL 8.0+, TiDB V8.0+
+- **Cloud**: TiDB Cloud, Neon DB (serverless options)
+- All support automatic schema migration
+
+### Key Configuration Files
+- `config.yml` / `config.example.yml`: Main configuration files (YAML format)
+- `.air.toml`: Air hot reload configuration for backend development
+- `.golangci.yml`: Go linting configuration
+- `.pre-commit-config.yaml`: Git pre-commit hooks
+- `frontend/vite.config.ts`: Frontend build configuration
+- `docker-compose.yml`: Docker Compose configuration for containerized deployment
+- `render.yaml`: Render deployment configuration
+
+### Configuration Management
+- **Primary Config**: `config.yml` (create from `config.example.yml`)
+- **Environment Variables**: All configuration options can be overridden with environment variables
+  - Format: `AXONHUB_{SECTION}_{KEY}` (e.g., `AXONHUB_SERVER_PORT=8090`)
+  - Nested keys use underscores (e.g., `AXONHUB_SERVER_CORS_ENABLED=true`)
+- **Database Support**: Configurable via `db.dialect` and `db.dsn`
+  - SQLite (default): `dialect: "sqlite3"`, `dsn: "axonhub.db"`
+  - PostgreSQL: `dialect: "postgres"`, `dsn: "host=..."`
+  - MySQL: `dialect: "mysql"`, `dsn: "user:pass@tcp(...)/axonhub"`
+  - TiDB: `dialect: "tidb"`, `dsn: "user.root:pass@tcp(...)/axonhub?tls=true"`
+
+## Common Development Tasks
+
+### Running a Single Test
+```bash
+# Backend: Run specific test
+go test -v -run TestFunctionName ./path/to/package
+
+# Frontend: Run specific test file
+pnpm test:e2e -- path/to/test.spec.ts
+```
+
+### Database Migration
+```bash
+# Generate new migration after schema changes
+make generate
+
+# The migration will be auto-applied on server start
+```
+
+### Debugging Stream Processing
+- Check `internal/llm/pipeline/` for stream aggregation logic
+- Monitor SSE connections in browser DevTools Network tab
+- Use request tracing with `AH-Trace-Id` header for debugging
+
+### Performance Optimization
+- Use request tracing to identify bottlenecks
+- Monitor database queries with Ent's built-in logging
+- Check channel load balancing configuration for optimal distribution

LICENSE

@@ -0,0 +1,210 @@
+AxonHub Licensing Overview:
+1. Priority: If a specific file contains a different license header, the terms in that header take precedence for that file.
+2. Scope: The `llm/` directory in this project is licensed under the GNU Lesser General Public License version 3.0 (LGPL-3.0). See `llm/LICENSE` for details.
+3. Scope: The `llm/bedrock/` directory in this project is copied from anthropic-sdk-go. See `llm/bedrock/NOTICE` for details.
+4. General: All other parts of this project are licensed under the Apache License, Version 2.0, unless otherwise specified.
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 looplj
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   

Makefile

@@ -0,0 +1,123 @@
+.PHONY: generate build backend frontend cleanup-db \
+	e2e-test e2e-backend-start e2e-backend-stop e2e-backend-status e2e-backend-restart e2e-backend-clean \
+	migration-test migration-test-all migration-test-all-dbs \
+	sync-faq sync-models filter-logs
+
+# Generate GraphQL and Ent code
+generate:
+	@echo "Generating GraphQL and Ent code..."
+	cd internal/server/gql && go generate
+	@echo "Generation completed!"
+
+generate-openapi:
+	@echo "Generating GraphQL and Ent code..."
+	cd internal/server/gql/openapi && go generate
+	@echo "Generation completed!"
+
+# Build the backend application
+build-backend:
+	@echo "Building axonhub backend..."
+	go build -ldflags "-s -w" -tags=nomsgpack -o axonhub ./cmd/axonhub
+	@echo "Backend build completed!"
+
+# Build the frontend application
+build-frontend:
+	@echo "Building axonhub frontend..."
+	cd frontend && pnpm vite build
+	@echo "Copying frontend dist to server static directory..."
+	rm -rf internal/server/static/dist/assets
+	mkdir -p internal/server/static/dist
+	cp -r frontend/dist/* internal/server/static/dist/
+	@echo "Frontend build completed!"
+
+# Build both frontend and backend
+build: build-frontend build-backend
+	@echo "Full build completed!"
+
+# Cleanup test database - remove all playwright test data
+cleanup-db:
+	@echo "Cleaning up playwright test data from database..."
+	@sqlite3 axonhub.db "DELETE FROM user_roles WHERE user_id IN (SELECT id FROM users WHERE email LIKE 'pw-test-%' OR first_name LIKE 'pw-test%');"
+	@sqlite3 axonhub.db "DELETE FROM user_projects WHERE user_id IN (SELECT id FROM users WHERE email LIKE 'pw-test-%' OR first_name LIKE 'pw-test%');"
+	@sqlite3 axonhub.db "DELETE FROM user_projects WHERE project_id IN (SELECT id FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%');"
+	@sqlite3 axonhub.db "DELETE FROM api_keys WHERE name LIKE 'pw-test-%';"
+	@sqlite3 axonhub.db "DELETE FROM api_keys WHERE user_id IN (SELECT id FROM users WHERE email LIKE 'pw-test-%' OR first_name LIKE 'pw-test%');"
+	@sqlite3 axonhub.db "DELETE FROM api_keys WHERE project_id IN (SELECT id FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%');"
+	@sqlite3 axonhub.db "DELETE FROM roles WHERE code LIKE 'pw-test-%' OR name LIKE 'pw-test-%';"
+	@sqlite3 axonhub.db "DELETE FROM roles WHERE project_id IN (SELECT id FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%');"
+	@sqlite3 axonhub.db "DELETE FROM usage_logs WHERE project_id IN (SELECT id FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%');"
+	@sqlite3 axonhub.db "DELETE FROM requests WHERE project_id IN (SELECT id FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%');"
+	@sqlite3 axonhub.db "DELETE FROM users WHERE email LIKE 'pw-test-%' OR first_name LIKE 'pw-test%';"
+	@sqlite3 axonhub.db "DELETE FROM projects WHERE slug LIKE 'pw-test-%' OR name LIKE 'pw-test-%';"
+	@echo "Cleanup completed!"
+
+# --- E2E Testing ---
+
+# Run the full E2E test suite
+e2e-test:
+	@echo "Running E2E tests..."
+	@./scripts/e2e/e2e-test.sh
+
+# Start the E2E backend service
+e2e-backend-start:
+	@echo "Starting E2E backend..."
+	@./scripts/e2e/e2e-backend.sh start
+
+# Stop the E2E backend service
+e2e-backend-stop:
+	@echo "Stopping E2E backend..."
+	@./scripts/e2e/e2e-backend.sh stop
+
+# Check E2E backend status
+e2e-backend-status:
+	@./scripts/e2e/e2e-backend.sh status
+
+# Restart the E2E backend service
+e2e-backend-restart:
+	@echo "Restarting E2E backend..."
+	@./scripts/e2e/e2e-backend.sh restart
+
+# Clean up E2E test files
+e2e-backend-clean:
+	@echo "Cleaning up E2E test files..."
+	@./scripts/e2e/e2e-backend.sh clean
+
+# --- Migration Testing ---
+
+# Test database migration from a specific tag
+# Usage: make migration-test TAG=v0.1.0
+migration-test:
+	@if [ -z "$(TAG)" ]; then echo "Error: TAG is required. Usage: make migration-test TAG=v0.1.0"; exit 1; fi
+	@echo "Running migration test from $(TAG)..."
+	@./scripts/migration/migration-test.sh $(TAG)
+
+# Run migration tests for all recent stable versions
+migration-test-all:
+	@echo "Running migration tests for all versions..."
+	@./scripts/migration/migration-test-all.sh
+
+# Test migration across all supported database types
+# Usage: make migration-test-all-dbs TAG=v0.1.0
+migration-test-all-dbs:
+	@if [ -z "$(TAG)" ]; then echo "Error: TAG is required. Usage: make migration-test-all-dbs TAG=v0.1.0"; exit 1; fi
+	@echo "Running migration tests across all DBs from $(TAG)..."
+	@./scripts/migration/test-migration-all-dbs.sh $(TAG)
+
+# --- Data Syncing ---
+
+# Sync FAQ from GitHub issues
+sync-faq:
+	@echo "Syncing FAQ from GitHub..."
+	@node ./scripts/sync/sync-github-faq.js
+
+# Sync model developers data
+sync-models:
+	@echo "Syncing model developers..."
+	@node ./scripts/sync/sync-model-developers.js
+
+# --- Utilities ---
+
+# Filter and analyze load balance logs
+filter-logs:
+	@echo "Filtering load balance logs..."
+	@./scripts/utils/filter-load-balance-logs.sh

cmd/axonhub/main.go

@@ -0,0 +1,281 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/andreazorzetto/yh/highlight"
+	"github.com/hokaccha/go-prettyjson"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxevent"
+	"gopkg.in/yaml.v3"
+
+	sdk "go.opentelemetry.io/otel/sdk/metric"
+
+	"github.com/looplj/axonhub/conf"
+	"github.com/looplj/axonhub/internal/build"
+	"github.com/looplj/axonhub/internal/ent"
+	"github.com/looplj/axonhub/internal/log"
+	"github.com/looplj/axonhub/internal/metrics"
+	"github.com/looplj/axonhub/internal/server"
+)
+
+func main() {
+	if len(os.Args) > 1 {
+		switch os.Args[1] {
+		case "config":
+			handleConfigCommand()
+			return
+		case "version", "--version", "-v":
+			showVersion()
+			return
+		case "help", "--help", "-h":
+			showHelp()
+		case "build-info":
+			showBuildInfo()
+			return
+		}
+	}
+
+	startServer()
+}
+
+func showBuildInfo() {
+	fmt.Println(build.GetBuildInfo())
+}
+
+type logger struct{}
+
+func (l *logger) LogEvent(event fxevent.Event) {
+	log.Debug(context.Background(), "fx event", log.Any("event", event))
+}
+
+func startServer() {
+	server.Run(
+		fx.WithLogger(func() fxevent.Logger {
+			return &logger{}
+		}),
+		fx.Provide(conf.Load),
+		fx.Provide(metrics.NewProvider),
+		fx.Invoke(func(lc fx.Lifecycle, server *server.Server, provider *sdk.MeterProvider, ent *ent.Client) {
+			lc.Append(fx.Hook{
+				OnStart: func(ctx context.Context) error {
+					if provider != nil {
+						return metrics.SetupMetrics(provider, server.Config.Name)
+					}
+
+					return nil
+				},
+				OnStop: func(ctx context.Context) error {
+					if provider != nil {
+						return provider.Shutdown(ctx)
+					}
+
+					return nil
+				},
+			})
+			lc.Append(fx.Hook{
+				OnStart: func(ctx context.Context) error {
+					go func() {
+						err := server.Run()
+						if err != nil {
+							log.Error(context.Background(), "server run error:", log.Cause(err))
+							os.Exit(1)
+						}
+					}()
+
+					return nil
+				},
+				OnStop: func(ctx context.Context) error {
+					err := server.Shutdown(ctx)
+					if err != nil {
+						log.Error(context.Background(), "server shutdown error:", log.Cause(err))
+					}
+
+					err = ent.Close()
+					if err != nil {
+						log.Error(context.Background(), "ent close error:", log.Cause(err))
+					}
+
+					return nil
+				},
+			})
+		}),
+	)
+}
+
+func handleConfigCommand() {
+	if len(os.Args) < 3 {
+		fmt.Println("Usage: axonhub config <preview|validate|get>")
+		os.Exit(1)
+	}
+
+	switch os.Args[2] {
+	case "preview":
+		configPreview()
+	case "validate":
+		configValidate()
+	case "get":
+		configGet()
+	default:
+		fmt.Println("Usage: axonhub config <preview|validate|get>")
+		os.Exit(1)
+	}
+}
+
+func configPreview() {
+	format := "yml"
+
+	for i := 3; i < len(os.Args); i++ {
+		if os.Args[i] == "--format" || os.Args[i] == "-f" {
+			if i+1 < len(os.Args) {
+				format = os.Args[i+1]
+			}
+		}
+	}
+
+	config, err := conf.Load()
+	if err != nil {
+		fmt.Printf("Failed to load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	var output string
+
+	switch format {
+	case "json":
+		b, err := prettyjson.Marshal(config)
+		if err != nil {
+			fmt.Printf("Failed to preview config: %v\n", err)
+			os.Exit(1)
+		}
+
+		output = string(b)
+	case "yml", "yaml":
+		b, err := yaml.Marshal(config)
+		if err != nil {
+			fmt.Printf("Failed to preview config: %v\n", err)
+			os.Exit(1)
+		}
+
+		output, err = highlight.Highlight(bytes.NewBuffer(b))
+		if err != nil {
+			fmt.Printf("Failed to preview config: %v\n", err)
+			os.Exit(1)
+		}
+	default:
+		fmt.Printf("Unsupported format: %s\n", format)
+		os.Exit(1)
+	}
+
+	fmt.Println(output)
+}
+
+func configValidate() {
+	config, err := conf.Load()
+	if err != nil {
+		fmt.Printf("Failed to load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	errors := validateConfig(config)
+
+	if len(errors) == 0 {
+		fmt.Println("Configuration is valid!")
+		return
+	}
+
+	fmt.Println("Configuration validation failed:")
+
+	for _, err := range errors {
+		fmt.Printf("  - %s\n", err)
+	}
+
+	os.Exit(1)
+}
+
+func validateConfig(config conf.Config) []string {
+	var errors []string
+
+	if config.APIServer.Port <= 0 || config.APIServer.Port > 65535 {
+		errors = append(errors, "server.port must be between 1 and 65535")
+	}
+
+	if config.DB.DSN == "" {
+		errors = append(errors, "db.dsn cannot be empty")
+	}
+
+	if config.Log.Name == "" {
+		errors = append(errors, "log.name cannot be empty")
+	}
+
+	if config.APIServer.CORS.Enabled && len(config.APIServer.CORS.AllowedOrigins) == 0 {
+		errors = append(errors, "server.cors.allowed_origins cannot be empty when CORS is enabled")
+	}
+
+	return errors
+}
+
+func configGet() {
+	if len(os.Args) < 4 {
+		fmt.Println("Usage: axonhub config get <key>")
+		fmt.Println("")
+		fmt.Println("Available keys:")
+		fmt.Println("  server.port    Server port number")
+		fmt.Println("  server.name    Server name")
+		fmt.Println("  db.dialect     Database dialect")
+		fmt.Println("  db.dsn         Database DSN")
+		os.Exit(1)
+	}
+
+	key := os.Args[3]
+
+	config, err := conf.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to load config: %v\n", err)
+		os.Exit(1)
+	}
+
+	var value any
+
+	switch key {
+	case "server.port":
+		value = config.APIServer.Port
+	case "server.name":
+		value = config.APIServer.Name
+	case "server.base_path":
+		value = config.APIServer.BasePath
+	case "server.debug":
+		value = config.APIServer.Debug
+	case "db.dialect":
+		value = config.DB.Dialect
+	case "db.dsn":
+		value = config.DB.DSN
+	default:
+		fmt.Fprintf(os.Stderr, "Unknown config key: %s\n", key)
+		os.Exit(1)
+	}
+
+	fmt.Println(value)
+}
+
+func showHelp() {
+	fmt.Println("AxonHub AI Gateway")
+	fmt.Println("")
+	fmt.Println("Usage:")
+	fmt.Println("  axonhub                    Start the server (default)")
+	fmt.Println("  axonhub config preview     Preview configuration")
+	fmt.Println("  axonhub config validate    Validate configuration")
+	fmt.Println("  axonhub config get <key>   Get a specific config value")
+	fmt.Println("  axonhub version            Show version")
+	fmt.Println("  axonhub help               Show this help message")
+	fmt.Println("")
+	fmt.Println("Options:")
+	fmt.Println("  -f, --format FORMAT       Output format for config preview (yml, json)")
+}
+
+func showVersion() {
+	fmt.Println(build.Version)
+}

conf/conf.go

@@ -0,0 +1,217 @@
+package conf
+
+import (
+	"context"
+	"encoding"
+	"errors"
+	"fmt"
+	"reflect"
+	"strings"
+	"time"
+
+	"github.com/go-viper/mapstructure/v2"
+	"github.com/spf13/viper"
+	"go.uber.org/fx"
+	"go.uber.org/zap/zapcore"
+
+	"github.com/looplj/axonhub/internal/log"
+	"github.com/looplj/axonhub/internal/metrics"
+	"github.com/looplj/axonhub/internal/pkg/xcache"
+	"github.com/looplj/axonhub/internal/server"
+	"github.com/looplj/axonhub/internal/server/db"
+	"github.com/looplj/axonhub/internal/server/gc"
+)
+
+type Config struct {
+	fx.Out `yaml:"-" json:"-"`
+
+	DB            db.Config           `conf:"db" yaml:"db" json:"db"`
+	Log           log.Config          `conf:"log" yaml:"log" json:"log"`
+	APIServer     server.Config       `conf:"server" yaml:"server" json:"server"`
+	Metrics       metrics.Config      `conf:"metrics" yaml:"metrics" json:"metrics"`
+	GC            gc.Config           `conf:"gc" yaml:"gc" json:"gc"`
+	Cache         xcache.Config       `conf:"cache" yaml:"cache" json:"cache"`
+	ProviderQuota providerQuotaConfig `conf:"provider_quota" yaml:"provider_quota" json:"provider_quota"`
+}
+
+type providerQuotaConfig struct {
+	CheckInterval time.Duration `conf:"check_interval" yaml:"check_interval" json:"check_interval"`
+}
+
+// Load loads configuration from YAML file and environment variables.
+func Load() (Config, error) {
+	v := viper.New()
+
+	// Set config file name and paths
+	v.SetConfigName("config")
+	v.SetConfigType("yml")
+	v.AddConfigPath(".")
+	v.AddConfigPath("/etc/axonhub/")
+	v.AddConfigPath("$HOME/.config/axonhub/")
+	v.AddConfigPath("./conf")
+
+	// Enable environment variable support
+	v.AutomaticEnv()
+	v.SetEnvPrefix("AXONHUB")
+	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+
+	// Set default values
+	setDefaults(v)
+
+	// Read config file
+	if err := v.ReadInConfig(); err != nil {
+		var configFileNotFoundError viper.ConfigFileNotFoundError
+		if !errors.As(err, &configFileNotFoundError) {
+			return Config{}, fmt.Errorf("failed to read config file: %w", err)
+		}
+		// Config file not found, use defaults and environment variables
+	}
+
+	// Parse log level from string before unmarshaling
+	logLevelStr := v.GetString("log.level")
+
+	logLevel, err := parseLogLevel(logLevelStr)
+	if err != nil {
+		return Config{}, fmt.Errorf("invalid log level '%s': %w", logLevelStr, err)
+	}
+	// Set the parsed log level back to viper for unmarshaling
+	v.Set("log.level", int(logLevel))
+
+	// Unmarshal config
+	var config Config
+	if err := v.Unmarshal(&config, func(dc *mapstructure.DecoderConfig) {
+		dc.DecodeHook = customizedDecodeHook
+		dc.TagName = "conf"
+	}); err != nil {
+		return Config{}, fmt.Errorf("failed to unmarshal config: %w", err)
+	}
+
+	log.Debug(context.Background(), "Config loaded successfully", log.Any("config", config))
+
+	return config, nil
+}
+
+var (
+	_TypeTextUnmarshaler = reflect.TypeFor[encoding.TextUnmarshaler]()
+	_TypeDuration        = reflect.TypeFor[time.Duration]()
+)
+
+func customizedDecodeHook(srcType reflect.Type, dstType reflect.Type, data any) (any, error) {
+	str, ok := data.(string)
+	if !ok {
+		return data, nil
+	}
+
+	switch {
+	case reflect.PointerTo(dstType).Implements(_TypeTextUnmarshaler):
+		value := reflect.New(dstType)
+
+		u, _ := value.Interface().(encoding.TextUnmarshaler)
+		if err := u.UnmarshalText([]byte(str)); err != nil {
+			return nil, err
+		}
+
+		return u, nil
+	case dstType == _TypeDuration:
+		if strings.TrimSpace(str) == "" {
+			return time.Duration(0), nil
+		}
+		return time.ParseDuration(str)
+	default:
+		return data, nil
+	}
+}
+
+// setDefaults sets default configuration values.
+func setDefaults(v *viper.Viper) {
+	// Server defaults
+	v.SetDefault("server.host", "0.0.0.0")
+	v.SetDefault("server.port", 8090)
+	v.SetDefault("server.name", "AxonHub")
+	v.SetDefault("server.base_path", "")
+	v.SetDefault("server.request_timeout", "30s")
+	v.SetDefault("server.llm_request_timeout", "600s")
+	v.SetDefault("server.trace.thread_header", "AH-Thread-Id")
+	v.SetDefault("server.trace.trace_header", "AH-Trace-Id")
+	v.SetDefault("server.trace.extra_trace_headers", []string{})
+	v.SetDefault("server.trace.extra_trace_body_fields", []string{})
+	v.SetDefault("server.trace.claude_code_trace_enabled", false)
+	v.SetDefault("server.trace.codex_trace_enabled", false)
+	v.SetDefault("server.debug", false)
+
+	// CORS defaults
+	v.SetDefault("server.cors.enabled", false)
+	v.SetDefault("server.cors.debug", false)
+	v.SetDefault("server.cors.allowed_origins", []string{"http://localhost:8090"})
+	v.SetDefault("server.cors.allowed_methods", []string{"GET", "POST", "DELETE", "PATCH", "PUT", "OPTIONS", "HEAD"})
+	v.SetDefault("server.cors.allowed_headers", []string{"Content-Type", "Authorization", "X-API-Key", "X-Goog-Api-Key", "X-Project-ID", "X-Thread-ID", "X-Trace-ID"})
+	v.SetDefault("server.cors.exposed_headers", []string{})
+	v.SetDefault("server.cors.allow_credentials", false)
+	v.SetDefault("server.cors.max_age", "30m")
+
+	// Database defaults
+	v.SetDefault("db.dialect", "sqlite3")
+	v.SetDefault("db.dsn", "file:axonhub.db?cache=shared&_fk=1&journal_mode=WAL")
+	v.SetDefault("db.debug", false)
+
+	// Log defaults
+	v.SetDefault("log.name", "axonhub")
+	v.SetDefault("log.debug", false)
+	v.SetDefault("log.skip_level", 1)
+	v.SetDefault("log.level", "info")
+	v.SetDefault("log.level_key", "level")
+	v.SetDefault("log.time_key", "time")
+	v.SetDefault("log.caller_key", "label")
+	v.SetDefault("log.function_key", "")
+	v.SetDefault("log.name_key", "logger")
+	v.SetDefault("log.encoding", "json")
+	v.SetDefault("log.includes", []string{})
+	v.SetDefault("log.excludes", []string{})
+	v.SetDefault("log.output", "stdio")
+	v.SetDefault("log.file.path", "logs/axonhub.log")
+	v.SetDefault("log.file.max_size", 100)   // MB
+	v.SetDefault("log.file.max_age", 30)     // days
+	v.SetDefault("log.file.max_backups", 10) // files
+	v.SetDefault("log.file.local_time", true)
+
+	// Metrics defaults
+	v.SetDefault("metrics.enabled", false)
+
+	// GC defaults
+	v.SetDefault("gc.cron", "0 2 * * *") // Daily at 2:00 AM
+
+	// Provider quota defaults
+	v.SetDefault("provider_quota.check_interval", "20m") // Check every 20 minutes
+
+	// Cache defaults
+	v.SetDefault("cache.mode", "memory")
+	v.SetDefault("cache.default_expiration", "5m")
+	v.SetDefault("cache.cleanup_interval", "10m")
+	v.SetDefault("cache.redis.addr", "")
+	v.SetDefault("cache.redis.url", "")
+	v.SetDefault("cache.redis.username", "")
+	v.SetDefault("cache.redis.password", "")
+	// Note: cache.redis.db has no default value to allow explicit override to 0
+	v.SetDefault("cache.redis.tls", false)
+	v.SetDefault("cache.redis.tls_insecure_skip_verify", false)
+}
+
+// parseLogLevel converts a string log level to zapcore.Level.
+func parseLogLevel(level string) (zapcore.Level, error) {
+	switch strings.ToLower(level) {
+	case "debug":
+		return zapcore.DebugLevel, nil
+	case "info":
+		return zapcore.InfoLevel, nil
+	case "warn", "warning":
+		return zapcore.WarnLevel, nil
+	case "error":
+		return zapcore.ErrorLevel, nil
+	case "panic":
+		return zapcore.PanicLevel, nil
+	case "fatal":
+		return zapcore.FatalLevel, nil
+	default:
+		return zapcore.InfoLevel, fmt.Errorf("unknown log level: %s", level)
+	}
+}

config.example.yml

@@ -0,0 +1,142 @@
+# AxonHub Configuration Example
+# Copy this file to config.yml and modify as needed
+
+# Server configuration
+server:
+  host: "0.0.0.0"               # Server host (env: AXONHUB_SERVER_HOST)
+  port: 8090                    # Server port (env: AXONHUB_SERVER_PORT)
+  name: "AxonHub"               # Server name (env: AXONHUB_SERVER_NAME)
+  base_path: ""                 # Base path for API routes (env: AXONHUB_SERVER_BASE_PATH)
+  request_timeout: "30s"        # Request timeout duration (env: AXONHUB_SERVER_REQUEST_TIMEOUT)
+  llm_request_timeout: "600s"   # LLM request timeout duration (env: AXONHUB_SERVER_LLM_REQUEST_TIMEOUT)
+  trace:
+    thread_header: "AH-Thread-Id" # Thread ID header name (env: AXONHUB_SERVER_TRACE_THREAD_HEADER)
+    trace_header: "AH-Trace-Id" # Trace ID header name (env: AXONHUB_SERVER_TRACE_TRACE_HEADER)
+    extra_trace_headers: [] # Extra trace headers (env: AXONHUB_SERVER_TRACE_EXTRA_TRACE_HEADERS)
+    extra_trace_body_fields: [] # Extra trace body fields (env: AXONHUB_SERVER_TRACE_EXTRA_TRACE_BODY_FIELDS)
+    claude_code_trace_enabled: false # Enable extracting trace IDs from Claude Code request metadata (env: AXONHUB_SERVER_TRACE_CLAUDE_CODE_TRACE_ENABLED)
+    codex_trace_enabled: false # Enable extracting trace IDs from Codex Session_id header (env: AXONHUB_SERVER_TRACE_CODEX_TRACE_ENABLED)
+  debug: false                  # Enable debug mode (env: AXONHUB_SERVER_DEBUG)
+  cors:
+    enabled: true               # Enable CORS middleware (env: AXONHUB_SERVER_CORS_ENABLED)
+    debug: false                # Enable CORS debug logging (env: AXONHUB_SERVER_CORS_DEBUG)
+    allowed_origins:            # Allowed origins for CORS (env: AXONHUB_SERVER_CORS_ALLOWED_ORIGINS)
+      - "http://localhost:3000"
+      - "http://localhost:5173"
+    allowed_methods:            # Allowed HTTP methods (env: AXONHUB_SERVER_CORS_ALLOWED_METHODS)
+      - "GET"
+      - "POST"
+      - "DELETE"
+      - "PATCH"
+      - "PUT"
+      - "OPTIONS"
+      - "HEAD"
+    allowed_headers:            # Allowed headers (env: AXONHUB_SERVER_CORS_ALLOWED_HEADERS)
+      - "Content-Type"
+      - "Authorization"
+      - "X-API-Key"
+      - "X-Goog-Api-Key"
+      - "X-Project-ID"
+      - "AH-Thread-Id"
+      - "AH-Trace-Id"
+      # Add any other headers your frontend sends
+    exposed_headers: []         # Exposed headers (env: AXONHUB_SERVER_CORS_EXPOSED_HEADERS)
+    allow_credentials: true     # Allow credentials (env: AXONHUB_SERVER_CORS_ALLOW_CREDENTIALS)
+    max_age: 1m                  # Max age for preflight cache in seconds (env: AXONHUB_SERVER_CORS_MAX_AGE)
+
+# Database configuration
+db:
+  dialect: "sqlite3"            # Database dialect: sqlite3, postgres, mysql (env: AXONHUB_DB_DIALECT)
+  dsn: "file:axonhub.db?cache=shared&_fk=1"  # Database connection string (env: AXONHUB_DB_DSN)
+  debug: false                  # Enable database debug logging (env: AXONHUB_DB_DEBUG)
+
+# Cache configuration
+cache:
+  # One of: memory, redis, two-level (memory + redis)
+  mode: "memory"                # (env: AXONHUB_CACHE_MODE)
+  
+  # Memory cache configuration
+  memory:
+    expiration: "5s"            # Memory cache TTL (env: AXONHUB_CACHE_MEMORY_EXPIRATION)
+    cleanup_interval: "10m"     # Memory cache cleanup interval (env: AXONHUB_CACHE_MEMORY_CLEANUP_INTERVAL)
+  
+  # Redis cache configuration
+  redis:
+    # Simple mode: Use addr for plain host:port
+    addr: ""                    # Redis address (host:port) (env: AXONHUB_CACHE_REDIS_ADDR)
+
+    # URL mode: Use url for full redis:// or rediss:// URLs (takes priority over addr)
+    # Supported formats:
+    #   - "redis://127.0.0.1:6379"
+    #   - "rediss://127.0.0.1:6380" (auto-enables TLS)
+    #   - "redis://user:pass@127.0.0.1:6379/0"
+    url: ""                     # Redis URL (env: AXONHUB_CACHE_REDIS_URL)
+
+    # Optional overrides (apply to both addr and url modes)
+    username: ""                # Overrides URL username (env: AXONHUB_CACHE_REDIS_USERNAME)
+    password: ""                # Overrides URL password (env: AXONHUB_CACHE_REDIS_PASSWORD)
+    db: 0                       # Overrides URL /db (env: AXONHUB_CACHE_REDIS_DB)
+    tls: false                  # Enable TLS for addr mode (env: AXONHUB_CACHE_REDIS_TLS)
+    tls_insecure_skip_verify: false # Skip TLS cert verification (env: AXONHUB_CACHE_REDIS_TLS_INSECURE_SKIP_VERIFY)
+    expiration: "30m"           # Redis cache TTL (env: AXONHUB_CACHE_REDIS_EXPIRATION)
+
+# Logging configuration
+log:
+  name: "axonhub"               # Logger name (env: AXONHUB_LOG_NAME)
+  debug: false                  # Enable debug logging (env: AXONHUB_LOG_DEBUG)
+  level: "info"                 # Log level: debug, info, warn, error, panic, fatal (env: AXONHUB_LOG_LEVEL)
+  level_key: "level"            # Key name for log level field (env: AXONHUB_LOG_LEVEL_KEY)
+  time_key: "time"              # Key name for timestamp field (env: AXONHUB_LOG_TIME_KEY)
+  caller_key: "label"           # Key name for caller info field (env: AXONHUB_LOG_CALLER_KEY)
+  function_key: ""              # Key name for function field (env: AXONHUB_LOG_FUNCTION_KEY)
+  name_key: "logger"            # Key name for logger name field (env: AXONHUB_LOG_NAME_KEY)
+  encoding: "json"              # Log encoding: json, console, console_json (env: AXONHUB_LOG_ENCODING)
+  includes: []                  # Logger names to include (env: AXONHUB_LOG_INCLUDES)
+  excludes: []                  # Logger names to exclude (env: AXONHUB_LOG_EXCLUDES)
+  output: "stdio"               # Output target: file or stdio (env: AXONHUB_LOG_OUTPUT)
+  file:                        # File-based logging configuration (env prefix: AXONHUB_LOG_FILE_*)
+    path: "logs/axonhub.log"   # Log file path (env: AXONHUB_LOG_FILE_PATH)
+    max_size: 100              # Max size in MB before rotation (env: AXONHUB_LOG_FILE_MAX_SIZE)
+    max_age: 30                # Max age in days to retain (env: AXONHUB_LOG_FILE_MAX_AGE)
+    max_backups: 10            # Max number of old log files to retain (env: AXONHUB_LOG_FILE_MAX_BACKUPS)
+    local_time: true           # Use local time for rotated files (env: AXONHUB_LOG_FILE_LOCAL_TIME)
+
+# Metrics configuration
+metrics:
+  enabled: false                 # Enable metrics collection (env: AXONHUB_METRICS_ENABLED)
+  exporter: 
+    type: "oltphttp"          # Metrics exporter type: prometheus, console (env: AXONHUB_METRICS_EXPORTER_TYPE)
+    endpoint: "localhost:8080" # Metrics exporter endpoint (env: AXONHUB_METRICS_EXPORTER_ENDPOINT)
+    insecure: true             # Enable insecure connection (env: AXONHUB_METRICS_EXPORTER_INSECURE)
+    
+
+# Garbage Collection configuration
+gc:
+  cron: "0 2 * * *"              # Cron expression for GC execution (env: AXONHUB_GC_CRON)
+                                 # This example runs daily at 2:00 AM
+                                 # Format: minute hour day month day_of_week
+                                 # Examples:
+                                 # "0 2 * * *"     - Daily at 2:00 AM
+                                 # "0 3 * * 0"     - Weekly on Sunday at 3:00 AM
+                                 # "0 4 1 * *"     - Monthly on 1st day at 4:00 AM
+
+# Provider Quota configuration
+provider_quota:
+  check_interval: "20m"          # Interval for checking provider quota status (env: AXONHUB_PROVIDER_QUOTA_CHECK_INTERVAL)
+                                 # Supported values: 1m, 2m, 3m, 4m, 5m, 6m, 10m, 12m, 15m, 20m, 30m, 1h, 2h, etc.
+                                 # Default: 20m
+                                 # Longer intervals reduce API calls but show less fresh quota data
+
+# Environment Variable Examples:
+# export AXONHUB_SERVER_PORT=8080
+# export AXONHUB_DB_DSN="postgres://user:pass@localhost/axonhub?sslmode=disable"
+# export AXONHUB_LOG_LEVEL="debug"
+# export AXONHUB_LOG_ENCODING="console"
+# export AXONHUB_LOG_OUTPUT="stdio"  # or "file"
+# export AXONHUB_LOG_FILE_PATH="/var/log/axonhub/axonhub.log"
+# export AXONHUB_LOG_FILE_MAX_SIZE=200
+# export AXONHUB_LOG_FILE_MAX_AGE=14
+# export AXONHUB_LOG_FILE_MAX_BACKUPS=7
+# export AXONHUB_SERVER_TRACE_HEADER="X-Trace-ID"
+# export AXONHUB_METRICS_ENABLED=false
+# export AXONHUB_GC_CRON="0 3 * * 0"  # Run weekly on Sunday at 3:00 AM

deploy/axonhub.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=AxonHub AI Gateway
+After=network.target
+
+[Service]
+Type=simple
+User=axonhub
+WorkingDirectory=/opt/axonhub
+ExecStart=/opt/axonhub/axonhub
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

deploy/helm/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

deploy/helm/Chart.yaml

@@ -0,0 +1,12 @@
+apiVersion: v2
+name: axonhub
+version: 0.1.0
+appVersion: "latest"
+description: A Helm chart for deploying AxonHub on Kubernetes
+type: application
+home: https://github.com/looplj/axonhub
+sources:
+  - https://github.com/looplj/axonhub
+maintainers:
+  - name: AxonHub Team
+    email: team@axonhub.ai

deploy/helm/README.md

@@ -0,0 +1,210 @@
+# AxonHub Helm Chart
+
+This Helm chart deploys AxonHub on Kubernetes with PostgreSQL database.
+
+## Prerequisites
+
+- Kubernetes 1.19+
+- Helm 3.0+
+- PV provisioner support in the underlying infrastructure (for persistence)
+
+## Installing the Chart
+
+To install the chart with the release name `axonhub`:
+
+```bash
+helm install axonhub ./deploy/helm
+```
+
+## Configuration
+
+The following table lists the configurable parameters of the AxonHub chart and their default values.
+
+### Global Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `global.imagePullSecrets` | Global Docker registry secret names as an array | `[]` |
+
+### AxonHub Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `axonhub.replicaCount` | Number of AxonHub replicas | `1` |
+| `axonhub.image.repository` | AxonHub image repository | `looplj/axonhub` |
+| `axonhub.image.tag` | AxonHub image tag | `latest` |
+| `axonhub.image.pullPolicy` | Image pull policy | `IfNotPresent` |
+| `axonhub.dbPassword` | Database password | `axonhub_password` |
+| `axonhub.service.type` | Kubernetes service type | `ClusterIP` |
+| `axonhub.service.port` | Service port | `8090` |
+| `axonhub.resources` | CPU/Memory resource requests/limits | `{}` |
+| `axonhub.persistence.enabled` | Enable persistence using PVC | `false` |
+| `axonhub.persistence.size` | PVC storage request size | `10Gi` |
+
+### PostgreSQL Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `postgresql.enabled` | Deploy PostgreSQL chart | `true` |
+| `postgresql.replicaCount` | Number of PostgreSQL replicas | `1` |
+| `postgresql.image.repository` | PostgreSQL image repository | `postgres` |
+| `postgresql.image.tag` | PostgreSQL image tag | `16-alpine` |
+| `postgresql.auth.postgresPassword` | PostgreSQL admin password | `axonhub_password` |
+| `postgresql.auth.username` | PostgreSQL user name | `axonhub` |
+| `postgresql.auth.password` | PostgreSQL user password | `axonhub_password` |
+| `postgresql.auth.database` | PostgreSQL database name | `axonhub` |
+| `postgresql.service.type` | Kubernetes service type | `ClusterIP` |
+| `postgresql.service.port` | PostgreSQL service port | `5432` |
+| `postgresql.primary.persistence.enabled` | Enable PostgreSQL persistence | `true` |
+| `postgresql.primary.persistence.size` | PVC storage request size | `8Gi` |
+
+### Ingress Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ingress.enabled` | Enable ingress controller resource | `false` |
+| `ingress.className` | IngressClass that will be used | `""` |
+| `ingress.annotations` | Ingress annotations | `{}` |
+| `ingress.hosts` | Ingress hostnames | `[{host: axonhub.local, paths: [{path: /, pathType: Prefix}]}]` |
+| `ingress.tls` | Ingress TLS configuration | `[]` |
+
+## Database Configuration Options
+
+### Using Internal PostgreSQL (Default)
+
+The chart includes PostgreSQL by default. This is suitable for:
+- Development environments
+- Small production deployments
+- When you want managed database within Kubernetes
+
+```yaml
+postgresql:
+  enabled: true  # Default setting
+```
+
+### Using External Database
+
+Disable internal PostgreSQL and configure external database connection:
+
+```yaml
+postgresql:
+  enabled: false
+
+axonhub:
+  env:
+    AXONHUB_DB_DSN: "postgres://username:password@external-db-host:5432/database?sslmode=require"
+```
+
+## Production Deployment
+
+For production deployments, you should:
+
+1. Change default passwords:
+```yaml
+axonhub:
+  dbPassword: "your-secure-password"
+
+postgresql:
+  auth:
+    postgresPassword: "your-secure-postgres-password"
+    password: "your-secure-password"
+```
+
+2. Enable persistence:
+```yaml
+axonhub:
+  persistence:
+    enabled: true
+    size: 20Gi
+
+postgresql:
+  primary:
+    persistence:
+      enabled: true
+      size: 20Gi
+```
+
+3. Configure resource limits:
+```yaml
+axonhub:
+  resources:
+    limits:
+      cpu: 2000m
+      memory: 2Gi
+    requests:
+      cpu: 1000m
+      memory: 1Gi
+
+postgresql:
+  resources:
+    limits:
+      cpu: 1000m
+      memory: 1Gi
+    requests:
+      cpu: 500m
+      memory: 512Mi
+```
+
+4. Enable ingress for external access:
+```yaml
+ingress:
+  enabled: true
+  className: "nginx"
+  hosts:
+    - host: axonhub.yourdomain.com
+      paths:
+        - path: /
+          pathType: Prefix
+```
+
+## Upgrading
+
+To upgrade the chart:
+
+```bash
+helm upgrade axonhub ./deploy/helm -f values-production.yaml
+```
+
+## Uninstalling
+
+To uninstall/delete the release:
+
+```bash
+helm uninstall axonhub
+```
+
+## Verification
+
+After installation, you can verify the deployment:
+
+```bash
+# Check pods status
+kubectl get pods
+
+# Check services
+kubectl get svc
+
+# Port forward to test
+kubectl port-forward svc/axonhub 8090:8090
+
+# Test health endpoint
+curl http://localhost:8090/health
+```
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Database connection failed**: Check PostgreSQL pod status and logs
+2. **Insufficient resources**: Adjust resource requests/limits in values.yaml
+3. **Persistent volume issues**: Ensure your cluster has PV provisioner configured
+4. **Ingress not working**: Verify ingress controller is installed and configured
+
+## Architecture
+
+The chart deploys:
+- AxonHub application as a Deployment
+- PostgreSQL database as a StatefulSet
+- Services for both components
+- Optional ingress for external access
+- Persistent volumes for data persistence

deploy/helm/install.bat

@@ -0,0 +1,38 @@
+@echo off
+setlocal
+
+set RELEASE_NAME=%1
+if "%RELEASE_NAME%"=="" set RELEASE_NAME=axonhub
+
+set NAMESPACE=%2
+if "%NAMESPACE%"=="" set NAMESPACE=default
+
+echo Installing AxonHub with Helm...
+echo Release name: %RELEASE_NAME%
+echo Namespace: %NAMESPACE%
+
+REM Create namespace if it doesn't exist
+kubectl create namespace %NAMESPACE% 2>nul || echo Namespace already exists
+
+REM Install the chart
+helm install %RELEASE_NAME% ./deploy/helm ^
+  --namespace %NAMESPACE% ^
+  --timeout 10m0s
+
+echo.
+echo Installation completed!
+echo.
+echo To access AxonHub:
+echo 1. Port forward the service:
+echo    kubectl port-forward svc/%RELEASE_NAME% 8090:8090 -n %NAMESPACE%
+echo.
+echo 2. Visit http://localhost:8090 in your browser
+echo.
+echo To check the status:
+echo    kubectl get pods -n %NAMESPACE%
+echo.
+echo To view logs:
+echo    kubectl logs -l app.kubernetes.io/name=axonhub -n %NAMESPACE%
+echo.
+echo To uninstall:
+echo    helm uninstall %RELEASE_NAME% -n %NAMESPACE%

deploy/helm/install.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# AxonHub Helm Installation Script
+
+set -e
+
+RELEASE_NAME=${1:-axonhub}
+NAMESPACE=${2:-default}
+
+echo "Installing AxonHub with Helm..."
+echo "Release name: $RELEASE_NAME"
+echo "Namespace: $NAMESPACE"
+
+# Create namespace if it doesn't exist
+kubectl create namespace $NAMESPACE 2>/dev/null || true
+
+# Install the chart
+helm install $RELEASE_NAME ./deploy/helm \
+  --namespace $NAMESPACE \
+  --timeout 10m0s
+
+echo ""
+echo "Installation completed!"
+echo ""
+echo "To access AxonHub:"
+echo "1. Port forward the service:"
+echo "   kubectl port-forward svc/$RELEASE_NAME 8090:8090 -n $NAMESPACE"
+echo ""
+echo "2. Visit http://localhost:8090 in your browser"
+echo ""
+echo "To check the status:"
+echo "   kubectl get pods -n $NAMESPACE"
+echo ""
+echo "To view logs:"
+echo "   kubectl logs -l app.kubernetes.io/name=axonhub -n $NAMESPACE"
+echo ""
+echo "To uninstall:"
+echo "   helm uninstall $RELEASE_NAME -n $NAMESPACE"

deploy/helm/templates/NOTES.txt

@@ -0,0 +1,43 @@
+Thank you for installing AxonHub!
+
+1. Get the application URL by running these commands:
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
+  {{- end }}
+{{- end }}
+{{- else if contains "NodePort" .Values.axonhub.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "axonhub.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.axonhub.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "axonhub.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "axonhub.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.axonhub.service.port }}
+{{- else if contains "ClusterIP" .Values.axonhub.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "axonhub.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  echo "Visit http://127.0.0.1:8090 to use your application"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8090:8090
+{{- end }}
+
+2. Check the status of your deployment:
+   kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "axonhub.name" . }}"
+
+3. View logs:
+   kubectl logs --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "axonhub.name" . }}" -c axonhub
+
+4. Access the application health endpoint:
+   kubectl port-forward --namespace {{ .Release.Namespace }} svc/{{ include "axonhub.fullname" . }} 8090:8090
+   # Then visit http://localhost:8090/health
+
+{{- if .Values.postgresql.enabled }}
+5. PostgreSQL database is available at:
+   Host: {{ include "axonhub.postgresql.serviceName" . }}.{{ .Release.Namespace }}.svc.cluster.local
+   Port: {{ .Values.postgresql.service.port }}
+   Database: {{ .Values.postgresql.auth.database }}
+   Username: {{ .Values.postgresql.auth.username }}
+{{- end }}
+
+WARNING: Default passwords are used. Please change them in production environments!

deploy/helm/templates/_helpers.tpl

@@ -0,0 +1,76 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "axonhub.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "axonhub.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "axonhub.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "axonhub.labels" -}}
+helm.sh/chart: {{ include "axonhub.chart" . }}
+{{ include "axonhub.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "axonhub.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "axonhub.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "axonhub.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "axonhub.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+PostgreSQL fullname
+*/}}
+{{- define "axonhub.postgresql.fullname" -}}
+{{- printf "%s-postgresql" (include "axonhub.fullname" .) | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+PostgreSQL service name
+*/}}
+{{- define "axonhub.postgresql.serviceName" -}}
+{{- include "axonhub.postgresql.fullname" . }}
+{{- end }}

deploy/helm/templates/data-pvc.yaml

@@ -0,0 +1,18 @@
+{{- if .Values.axonhub.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "axonhub.fullname" . }}-data
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub
+spec:
+  accessModes:
+    {{- toYaml .Values.axonhub.persistence.accessModes | nindent 4 }}
+  resources:
+    requests:
+      storage: {{ .Values.axonhub.persistence.size }}
+  {{- if .Values.axonhub.persistence.storageClass }}
+  storageClassName: {{ .Values.axonhub.persistence.storageClass }}
+  {{- end }}
+{{- end }}

deploy/helm/templates/deployment.yaml

@@ -0,0 +1,82 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "axonhub.fullname" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub
+spec:
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.axonhub.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "axonhub.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: axonhub
+  template:
+    metadata:
+      {{- with .Values.axonhub.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      labels:
+        {{- include "axonhub.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: axonhub
+    spec:
+      {{- with .Values.global.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "axonhub.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.axonhub.podSecurityContext | nindent 8 }}
+      {{- if .Values.postgresql.enabled }}
+      initContainers:
+        - name: wait-for-postgres
+          image: busybox:1.36
+          command: ['sh', '-c', 'until nc -z {{ include "axonhub.postgresql.serviceName" . }} 5432; do echo waiting for postgresql; sleep 2; done;']
+      {{- end }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.axonhub.securityContext | nindent 12 }}
+          image: "{{ .Values.axonhub.image.repository }}:{{ .Values.axonhub.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.axonhub.image.pullPolicy }}
+          env:
+            {{- range $key, $value := .Values.axonhub.env }}
+            - name: {{ $key }}
+              value: {{ $value | quote }}
+            {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.axonhub.service.port }}
+              protocol: TCP
+          livenessProbe:
+            {{- toYaml .Values.axonhub.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.axonhub.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.axonhub.resources | nindent 12 }}
+          {{- if .Values.axonhub.persistence.enabled }}
+          volumeMounts:
+            - name: data
+              mountPath: /data
+          {{- end }}
+      {{- with .Values.axonhub.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.axonhub.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.axonhub.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- if .Values.axonhub.persistence.enabled }}
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: {{ include "axonhub.fullname" . }}-data
+      {{- end }}

deploy/helm/templates/hpa.yaml

@@ -0,0 +1,33 @@
+{{- if .Values.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "axonhub.fullname" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "axonhub.fullname" . }}
+  minReplicas: {{ .Values.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+  metrics:
+    {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+    {{- end }}
+    {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    {{- end }}
+{{- end }}

deploy/helm/templates/ingress.yaml

@@ -0,0 +1,62 @@
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "axonhub.fullname" . -}}
+{{- $svcPort := .Values.axonhub.service.port -}}
+{{- if and .Values.ingress.className (not (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion)) }}
+  {{- if not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class") }}
+  {{- $_ := set .Values.ingress.annotations "kubernetes.io/ingress.class" .Values.ingress.className}}
+  {{- end }}
+{{- end }}
+{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1
+{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1beta1
+{{- else -}}
+apiVersion: extensions/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if and .Values.ingress.className (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion) }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    {{- range .Values.ingress.tls }}
+    - hosts:
+        {{- range .hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ .secretName }}
+    {{- end }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            {{- if and .pathType (semverCompare ">=1.18-0" $.Capabilities.KubeVersion.GitVersion) }}
+            pathType: {{ .pathType }}
+            {{- end }}
+            backend:
+              {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
+              service:
+                name: {{ $fullName }}
+                port:
+                  number: {{ $svcPort }}
+              {{- else }}
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+              {{- end }}
+          {{- end }}
+    {{- end }}
+{{- end }}

deploy/helm/templates/postgresql-service.yaml

@@ -0,0 +1,19 @@
+{{- if .Values.postgresql.enabled -}}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "axonhub.postgresql.serviceName" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: postgresql
+spec:
+  type: {{ .Values.postgresql.service.type }}
+  ports:
+    - port: {{ .Values.postgresql.service.port }}
+      targetPort: postgresql
+      protocol: TCP
+      name: postgresql
+  selector:
+    {{- include "axonhub.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: postgresql
+{{- end }}

deploy/helm/templates/postgresql-statefulset.yaml

@@ -0,0 +1,79 @@
+{{- if .Values.postgresql.enabled -}}
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: {{ include "axonhub.postgresql.fullname" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: postgresql
+spec:
+  serviceName: {{ include "axonhub.postgresql.serviceName" . }}
+  replicas: {{ .Values.postgresql.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "axonhub.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: postgresql
+  template:
+    metadata:
+      labels:
+        {{- include "axonhub.selectorLabels" . | nindent 8 }}
+        app.kubernetes.io/component: postgresql
+    spec:
+      {{- with .Values.global.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      securityContext:
+        {{- toYaml .Values.postgresql.podSecurityContext | nindent 8 }}
+      containers:
+        - name: postgresql
+          securityContext:
+            {{- toYaml .Values.postgresql.securityContext | nindent 12 }}
+          image: "{{ .Values.postgresql.image.repository }}:{{ .Values.postgresql.image.tag }}"
+          imagePullPolicy: {{ .Values.postgresql.image.pullPolicy }}
+          env:
+            - name: POSTGRES_DB
+              value: {{ .Values.postgresql.auth.database | quote }}
+            - name: POSTGRES_USER
+              value: {{ .Values.postgresql.auth.username | quote }}
+            - name: POSTGRES_PASSWORD
+              value: {{ .Values.postgresql.auth.password | quote }}
+          ports:
+            - name: postgresql
+              containerPort: 5432
+              protocol: TCP
+          livenessProbe:
+            {{- toYaml .Values.postgresql.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.postgresql.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.postgresql.resources | nindent 12 }}
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
+              subPath: postgresql-db
+      {{- with .Values.postgresql.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.postgresql.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.postgresql.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+      spec:
+        accessModes:
+          {{- toYaml .Values.postgresql.primary.persistence.accessModes | nindent 10 }}
+        resources:
+          requests:
+            storage: {{ .Values.postgresql.primary.persistence.size }}
+        {{- if .Values.postgresql.primary.persistence.storageClass }}
+        storageClassName: {{ .Values.postgresql.primary.persistence.storageClass }}
+        {{- end }}
+{{- end }}

deploy/helm/templates/service.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "axonhub.fullname" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub
+spec:
+  type: {{ .Values.axonhub.service.type }}
+  ports:
+    - port: {{ .Values.axonhub.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "axonhub.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: axonhub

deploy/helm/templates/serviceaccount.yaml

@@ -0,0 +1,12 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "axonhub.serviceAccountName" . }}
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}

deploy/helm/templates/tests/test-connection.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: "{{ include "axonhub.fullname" . }}-test-connection"
+  labels:
+    {{- include "axonhub.labels" . | nindent 4 }}
+    app.kubernetes.io/component: test
+  annotations:
+    "helm.sh/hook": test
+spec:
+  containers:
+    - name: wget
+      image: busybox
+      command: ['wget']
+      args: ['{{ include "axonhub.fullname" . }}:{{ .Values.axonhub.service.port }}']
+  restartPolicy: Never

deploy/helm/values-production.yaml

@@ -0,0 +1,171 @@
+# Production values for AxonHub Helm chart
+# Copy this file and modify according to your production requirements
+
+# Global configuration
+global:
+  imagePullSecrets: []
+  # Add your image pull secrets here if using private registry
+  # - name: my-registry-secret
+
+# AxonHub application configuration
+axonhub:
+  replicaCount: 2
+  
+  image:
+    repository: looplj/axonhub
+    tag: "latest"  # Consider using specific version in production
+    pullPolicy: IfNotPresent
+  
+  # Environment variables - customize the database connection string for your environment
+  env:
+    AXONHUB_DB_DIALECT: postgres
+    # For external database - modify this connection string
+    AXONHUB_DB_DSN: postgres://axonhub:your_db_password@your-db-host:5432/axonhub?sslmode=require
+    # For internal PostgreSQL - uncomment below and comment above
+    # AXONHUB_DB_DSN: postgres://axonhub:CHANGE_ME_POSTGRES_USER_123456@axonhub-postgresql:5432/axonhub?sslmode=disable
+  
+  # Environment variables are defined above in the axonhub.env section
+  
+  # Service configuration
+  service:
+    type: ClusterIP
+    port: 8090
+  
+  # Resources - adjust based on your workload
+  resources:
+    limits:
+      cpu: 2000m
+      memory: 2Gi
+    requests:
+      cpu: 1000m
+      memory: 1Gi
+  
+  # Health checks
+  livenessProbe:
+    httpGet:
+      path: /health
+      port: 8090
+    initialDelaySeconds: 60
+    periodSeconds: 30
+    timeoutSeconds: 10
+    failureThreshold: 3
+  
+  readinessProbe:
+    httpGet:
+      path: /health
+      port: 8090
+    initialDelaySeconds: 30
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 3
+  
+  # Security context
+  podSecurityContext:
+    fsGroup: 1000
+  
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+  
+  # Persistence - enable for production
+  persistence:
+    enabled: true
+    size: 20Gi
+    storageClass: ""  # Specify your storage class
+    accessModes:
+      - ReadWriteOnce
+
+# PostgreSQL configuration - set to false if using external database
+postgresql:
+  enabled: true
+  replicaCount: 1
+  
+  image:
+    repository: postgres
+    tag: "16-alpine"
+    pullPolicy: IfNotPresent
+  
+  # Security - CHANGE THESE VALUES IN PRODUCTION
+  auth:
+    postgresPassword: "CHANGE_ME_POSTGRES_ADMIN_123456"
+    username: "axonhub"
+    password: "CHANGE_ME_POSTGRES_USER_123456"
+    database: "axonhub"
+  
+  # Service configuration
+  service:
+    type: ClusterIP
+    port: 5432
+  
+  # Resources
+  resources:
+    limits:
+      cpu: 1000m
+      memory: 1Gi
+    requests:
+      cpu: 500m
+      memory: 512Mi
+  
+  # Persistence
+  primary:
+    persistence:
+      enabled: true
+      size: 20Gi
+      storageClass: ""  # Specify your storage class
+      accessModes:
+        - ReadWriteOnce
+  
+  # Health checks
+  livenessProbe:
+    exec:
+      command:
+        - pg_isready
+        - -U
+        - axonhub
+    initialDelaySeconds: 30
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 6
+  
+  readinessProbe:
+    exec:
+      command:
+        - pg_isready
+        - -U
+        - axonhub
+    initialDelaySeconds: 5
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 6
+
+# Ingress configuration - enable for external access
+ingress:
+  enabled: true
+  className: "nginx"  # Adjust based on your ingress controller
+  annotations:
+    # Add your ingress annotations here
+    # nginx.ingress.kubernetes.io/rewrite-target: /
+    cert-manager.io/cluster-issuer: "letsencrypt-prod"  # For SSL certificates
+  hosts:
+    - host: axonhub.yourdomain.com  # Change to your domain
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: axonhub-tls
+      hosts:
+        - axonhub.yourdomain.com  # Change to your domain
+
+# Autoscaling - enable for production workloads
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 80
+
+# Service account
+serviceAccount:
+  create: true
+  annotations: {}
+  name: ""

deploy/helm/values.yaml

@@ -0,0 +1,165 @@
+# Default values for axonhub.
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+global:
+  # Global image pull secrets
+  imagePullSecrets: []
+
+# AxonHub application configuration
+axonhub:
+  replicaCount: 1
+  
+  image:
+    repository: looplj/axonhub
+    pullPolicy: IfNotPresent
+    tag: "latest"
+  
+  # Environment variables for AxonHub
+  env:
+    AXONHUB_DB_DIALECT: postgres
+    # Full database connection string - customize this for your environment
+    AXONHUB_DB_DSN: postgres://axonhub:axonhub_password@axonhub-postgresql:5432/axonhub?sslmode=disable
+  
+  # Service configuration
+  service:
+    type: ClusterIP
+    port: 8090
+    
+  # Resource limits and requests
+  resources:
+    limits:
+      cpu: 1000m
+      memory: 1Gi
+    requests:
+      cpu: 500m
+      memory: 512Mi
+  
+  # Health checks
+  livenessProbe:
+    httpGet:
+      path: /health
+      port: 8090
+    initialDelaySeconds: 60
+    periodSeconds: 30
+    timeoutSeconds: 10
+    failureThreshold: 3
+  
+  readinessProbe:
+    httpGet:
+      path: /health
+      port: 8090
+    initialDelaySeconds: 30
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 3
+  
+  # Security context
+  podSecurityContext:
+    fsGroup: 1000
+  
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+  
+  # Node selection
+  nodeSelector: {}
+  tolerations: []
+  affinity: {}
+  
+  # Persistent volume for data storage (optional)
+  persistence:
+    enabled: false
+    size: 10Gi
+    storageClass: ""
+    accessModes:
+      - ReadWriteOnce
+
+# PostgreSQL database configuration
+postgresql:
+  enabled: true
+  replicaCount: 1
+  
+  image:
+    repository: postgres
+    tag: "16-alpine"
+    pullPolicy: IfNotPresent
+  
+  # Database credentials
+  auth:
+    postgresPassword: "axonhub_password"  # Should be overridden in production
+    username: "axonhub"
+    password: "axonhub_password"  # Should be overridden in production
+    database: "axonhub"
+  
+  # Service configuration
+  service:
+    type: ClusterIP
+    port: 5432
+  
+  # Resource limits
+  resources:
+    limits:
+      cpu: 500m
+      memory: 512Mi
+    requests:
+      cpu: 250m
+      memory: 256Mi
+  
+  # Persistence
+  primary:
+    persistence:
+      enabled: true
+      size: 8Gi
+      storageClass: ""
+      accessModes:
+        - ReadWriteOnce
+  
+  # Health check
+  livenessProbe:
+    exec:
+      command:
+        - pg_isready
+        - -U
+        - axonhub
+    initialDelaySeconds: 30
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 6
+  
+  readinessProbe:
+    exec:
+      command:
+        - pg_isready
+        - -U
+        - axonhub
+    initialDelaySeconds: 5
+    periodSeconds: 10
+    timeoutSeconds: 5
+    failureThreshold: 6
+
+# Ingress configuration
+ingress:
+  enabled: true
+  className: ""
+  annotations: {}
+  hosts:
+    - host: axonhub.local
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+
+# Autoscaling configuration
+autoscaling:
+  enabled: false
+  minReplicas: 1
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 80
+
+# Service account configuration
+serviceAccount:
+  create: true
+  annotations: {}
+  name: ""

deploy/install.bat

@@ -0,0 +1,15 @@
+@echo off
+setlocal
+
+REM AxonHub Windows installer wrapper (.bat)
+
+where powershell >NUL 2>NUL
+if %ERRORLEVEL% NEQ 0 (
+  echo [ERROR] PowerShell is required to run this installer.
+  echo Please run on Windows 7+ with PowerShell available in PATH.
+  exit /b 1
+)
+
+set "SCRIPT_DIR=%~dp0"
+powershell -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%install.ps1" %*
+exit /b %ERRORLEVEL%

deploy/install.ps1

@@ -0,0 +1,217 @@
+param(
+    [Parameter(ValueFromRemainingArguments=$true)]
+    [string[]]$ArgsFromCmd
+)
+
+$ErrorActionPreference = 'Stop'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+function Write-Info([string]$m){ Write-Host "[INFO] $m" -ForegroundColor Cyan }
+function Write-Success([string]$m){ Write-Host "[SUCCESS] $m" -ForegroundColor Green }
+function Write-Warn([string]$m){ Write-Host "[WARNING] $m" -ForegroundColor Yellow }
+function Write-Err([string]$m){ Write-Host "[ERROR] $m" -ForegroundColor Red }
+
+$Repo = 'looplj/axonhub'
+$Api = "https://api.github.com/repos/$Repo"
+
+$IncludeBeta = $false
+$IncludeRC   = $false
+$VerboseFlag = $false
+$Version     = $env:AXONHUB_VERSION
+
+function Show-Usage {
+  Write-Host @'
+AxonHub Installer (Windows)
+
+Usage:
+  install.bat [options] [version]
+
+Options:
+  -b, --beta       Consider beta pre-releases
+  -r, --rc         Consider release-candidate pre-releases
+  -v, --verbose    Print extra debug logs
+  -h, --help       Show this help and exit
+'@
+}
+
+# Parse args
+foreach($a in $ArgsFromCmd){
+  switch -Regex ($a){
+    '^(--beta|-b)$'    { $IncludeBeta = $true; continue }
+    '^(--rc|-r)$'      { $IncludeRC   = $true; continue }
+    '^(--verbose|-v)$' { $VerboseFlag = $true; continue }
+    '^(--help|-h)$'    { Show-Usage; exit 0 }
+    default            { if(-not $Version){ $Version = $a } else { Write-Warn "Ignoring extra argument: $a" } }
+  }
+}
+
+function Get-Platform {
+  $archEnv = $env:PROCESSOR_ARCHITECTURE
+  switch ($archEnv.ToLower()){
+    'amd64' { return 'windows_amd64' }
+    'arm64' { return 'windows_arm64' }
+    default { Write-Err "Unsupported architecture: $archEnv"; exit 1 }
+  }
+}
+
+function Invoke-GHApi([string]$url){
+  $headers = @{
+    'Accept'='application/vnd.github+json'
+    'X-GitHub-Api-Version'='2022-11-28'
+    'User-Agent'='axonhub-installer'
+  }
+  if($env:GITHUB_TOKEN){ $headers['Authorization'] = "Bearer $($env:GITHUB_TOKEN)" }
+  return Invoke-RestMethod -Method GET -Uri $url -Headers $headers -ErrorAction Stop
+}
+
+function Get-LatestReleaseTag {
+  try {
+    $json = Invoke-GHApi "$Api/releases/latest"
+    return $json.tag_name
+  } catch {
+    # Fallback to HTML redirect (best-effort)
+    Write-Warn "API failed or rate-limited, falling back to HTML redirect..."
+    try {
+      $resp = Invoke-WebRequest -Uri "https://github.com/$Repo/releases/latest" -Headers @{ 'User-Agent'='axonhub-installer' } -MaximumRedirection 0 -ErrorAction Stop
+    } catch { $resp = $_.Exception.Response }
+    if($resp -and $resp.Headers['Location']){
+      $loc = $resp.Headers['Location']
+      if($loc -match '/tag/([^/]+)$'){ return $matches[1] }
+    }
+    Write-Err "Could not determine latest release version"
+    exit 1
+  }
+}
+
+function Get-LatestVersion([bool]$includeBeta,[bool]$includeRC){
+  if(-not $includeBeta -and -not $includeRC){ return Get-LatestReleaseTag }
+  Write-Info "Fetching releases (beta=$includeBeta, rc=$includeRC) ..."
+  try {
+    $rels = Invoke-GHApi "$Api/releases?per_page=100"
+    $filtered = $rels | Where-Object { -not $_.draft }
+    if($includeBeta -and $includeRC){
+      $filtered = $filtered | Where-Object { $_.tag_name -match '-beta' -or $_.tag_name -match '-rc' }
+    } elseif($includeBeta){
+      $filtered = $filtered | Where-Object { $_.tag_name -match '-beta' }
+    } else {
+      $filtered = $filtered | Where-Object { $_.tag_name -match '-rc' }
+    }
+    if(-not $filtered){
+      Write-Warn 'No matching pre-release found; falling back to latest stable.'
+      return Get-LatestReleaseTag
+    }
+    # GitHub API returns releases in reverse chronological order; take the first
+    return ($filtered | Select-Object -First 1).tag_name
+  } catch {
+    Write-Warn 'Failed to fetch releases; falling back to latest stable.'
+    return Get-LatestReleaseTag
+  }
+}
+
+function Get-AssetUrl([string]$version,[string]$platform){
+  Write-Info "Resolving asset for $version ($platform) ..."
+  try {
+    $tag = $version
+    $json = Invoke-GHApi "$Api/releases/tags/$tag"
+    $asset = $json.assets | Where-Object { $_.browser_download_url -match $platform -and $_.browser_download_url -like '*.zip' } | Select-Object -First 1
+    if($asset){ return $asset.browser_download_url }
+  } catch {}
+  # Fallback by pattern
+  $clean = $version.TrimStart('v')
+  $file = "axonhub_${clean}_${platform}.zip"
+  $candidate = "https://github.com/$Repo/releases/download/$version/$file"
+  try {
+    $head = Invoke-WebRequest -Uri $candidate -Method Head -ErrorAction Stop
+    return $candidate
+  } catch {
+    Write-Err "Could not find asset for platform $platform in release $version"
+    exit 1
+  }
+}
+
+function Ensure-Dirs([string]$path){ if(-not (Test-Path $path)){ New-Item -ItemType Directory -Force -Path $path | Out-Null } }
+
+# Main
+Write-Info 'Starting AxonHub installation...'
+
+$Platform = Get-Platform
+Write-Info "Detected platform: $Platform"
+
+if(-not $Version){ $Version = Get-LatestVersion $IncludeBeta $IncludeRC }
+Write-Info "Using version: $Version"
+
+$BaseDir   = Join-Path $env:LOCALAPPDATA 'AxonHub'
+$ConfigDir = $BaseDir
+$DataDir   = $BaseDir
+$LogDir    = $BaseDir
+Ensure-Dirs $BaseDir
+Ensure-Dirs (Join-Path $BaseDir 'logs')
+
+$AssetUrl = Get-AssetUrl $Version $Platform
+$TempDir = New-Item -ItemType Directory -Path (Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName())) -Force
+$ZipPath = Join-Path $TempDir 'axonhub.zip'
+Write-Info "Downloading: $AssetUrl"
+Invoke-WebRequest -Uri $AssetUrl -OutFile $ZipPath -UseBasicParsing
+
+Write-Info 'Extracting archive...'
+Expand-Archive -Path $ZipPath -DestinationPath $TempDir -Force
+
+$BinaryPath = Get-ChildItem -Path $TempDir -Recurse -Filter 'axonhub.exe' -File | Select-Object -First 1 | ForEach-Object { $_.FullName }
+if(-not $BinaryPath){ Write-Err 'axonhub.exe not found in archive'; exit 1 }
+
+$TargetBinary = Join-Path $BaseDir 'axonhub.exe'
+Copy-Item -Path $BinaryPath -Destination $TargetBinary -Force
+
+# Create default config if missing
+$ConfigFile = Join-Path $BaseDir 'config.yml'
+if(-not (Test-Path $ConfigFile)){
+  Write-Info 'Creating default configuration...'
+  $baseForDSN = ($BaseDir -replace '\\','/')
+  @"
+server:
+  port: 8090
+  name: "AxonHub"
+  debug: false
+
+db:
+  dialect: "sqlite3"
+  dsn: "$baseForDSN/axonhub.db?cache=shared&_fk=1&journal_mode=WAL"
+
+cache:
+  mode: "memory"
+  cache:
+    expiration: "5s"
+    cleanup_interval: "5s"
+    
+log:
+  level: "info"
+  encoding: "json"
+  output: "file"
+  file:
+    path: "$baseForDSN/logs/axonhub.log"
+    max_size: 100
+    max_age: 30
+    max_backups: 10
+    local_time: true
+"@ | Set-Content -Path $ConfigFile -Encoding UTF8
+}
+
+Write-Success 'AxonHub installation completed!'
+
+# Get configured port for display
+$port = 8090
+if(Test-Path $TargetBinary){
+  try {
+    $configPort = & $TargetBinary config get server.port 2>$null
+    if($configPort -match '^[0-9]+$'){
+      $port = $configPort
+    }
+  } catch {}
+}
+
+Write-Info "Next steps:"
+Write-Host "  1. Edit configuration: $ConfigFile"
+Write-Host "  2. Start AxonHub: start.bat"
+Write-Host "  3. Stop AxonHub: stop.bat"
+Write-Host "  4. View logs: $BaseDir\axonhub.log (or logs\axonhub.log in config)"
+Write-Host "  5. Access web interface: http://localhost:$port"

deploy/install.sh

@@ -0,0 +1,550 @@
+#!/bin/bash
+
+# AxonHub Installation Script
+# This script downloads and installs the latest AxonHub release for direct start/stop usage (no systemd)
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+INSTALL_DIR="/usr/local/bin"
+# Resolve non-root user's HOME when running via sudo
+if [[ -n "$SUDO_USER" && "$SUDO_USER" != "root" ]]; then
+    USER_HOME="$(eval echo ~${SUDO_USER})"
+else
+    USER_HOME="$HOME"
+fi
+BASE_DIR="${USER_HOME}/.config/axonhub"
+CONFIG_DIR="${BASE_DIR}"
+DATA_DIR="${BASE_DIR}"
+LOG_DIR="${BASE_DIR}"
+SERVICE_USER="axonhub"
+
+# GitHub repository
+REPO="looplj/axonhub"
+GITHUB_API="https://api.github.com/repos/${REPO}"
+
+# CLI options (default: exclude beta/rc)
+INCLUDE_BETA="false"
+INCLUDE_RC="false"
+VERBOSE="false"
+
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1" 1>&2
+}
+
+curl_gh() {
+    # Curl helper for GitHub with proper headers and optional token
+    local url="$1"
+    local headers=(
+        -H "Accept: application/vnd.github+json"
+        -H "X-GitHub-Api-Version: 2022-11-28"
+        -H "User-Agent: axonhub-installer"
+    )
+    if [[ -n "$GITHUB_TOKEN" ]]; then
+        headers+=( -H "Authorization: Bearer $GITHUB_TOKEN" )
+    fi
+    curl -fsSL "${headers[@]}" "$url"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1" 1>&2
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1" 1>&2
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1" 1>&2
+}
+
+# Verbose logger
+debug() {
+    if [[ "$VERBOSE" == "true" ]]; then
+        echo -e "${YELLOW}[DEBUG]${NC} $1" 1>&2
+    fi
+}
+
+usage() {
+    cat 1>&2 <<EOF
+AxonHub Installer
+
+Usage:
+  sudo ./install.sh [options] [version]
+
+Options:
+  -b, --beta       Consider beta pre-releases when resolving latest version
+  -r, --rc         Consider release-candidate (rc) pre-releases when resolving latest version
+  -v, --verbose    Print extra debug logs
+  -h, --help       Show this help and exit
+
+Notes:
+  - By default, beta/rc versions are filtered out and the latest stable release is used.
+  - If a version is provided (e.g., v1.2.3), flags are ignored and that version is used.
+  - If both --beta and --rc are provided, the newest matching pre-release is selected.
+EOF
+}
+
+check_root() {
+    if [[ $EUID -ne 0 ]]; then
+        print_error "This script must be run as root (use sudo)"
+        exit 1
+    fi
+}
+
+detect_architecture() {
+    local arch=$(uname -m)
+    local os=$(uname -s | tr '[:upper:]' '[:lower:]')
+    
+    case $arch in
+        x86_64|amd64)
+            arch="amd64"
+            ;;
+        aarch64|arm64)
+            arch="arm64"
+            ;;
+        *)
+            print_error "Unsupported architecture: $arch"
+            exit 1
+            ;;
+    esac
+    
+    case $os in
+        linux)
+            os="linux"
+            ;;
+        darwin)
+            os="darwin"
+            ;;
+        *)
+            print_error "Unsupported operating system: $os"
+            exit 1
+            ;;
+    esac
+    
+    echo "${os}_${arch}"
+}
+
+get_latest_release() {
+    print_info "Fetching latest release information..."
+    
+    local tag_name
+    # Try GitHub API first
+    if json=$(curl_gh "${GITHUB_API}/releases/latest" 2>/dev/null); then
+        tag_name=$(echo "$json" | tr -d '\n\r\t' | sed -nE 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' | head -1)
+    fi
+    
+    # Fallback: follow the HTML redirect to the latest tag
+    if [[ -z "$tag_name" ]]; then
+        print_warning "API failed or rate-limited, falling back to HTML redirect..."
+        local final_url
+        final_url=$(curl -fsSL -H "User-Agent: axonhub-installer" -o /dev/null -w "%{url_effective}" "https://github.com/${REPO}/releases/latest" || true)
+        tag_name=$(echo "$final_url" | sed -nE 's#.*/tag/([^/]+).*#\1#p' | head -1)
+    fi
+    
+    if [[ -z "$tag_name" ]]; then
+        print_error "Could not determine latest release version"
+        exit 1
+    fi
+    
+    debug "Selected tag: $tag_name"
+    echo "$tag_name"
+}
+
+# Get the latest version based on flags (default stable; with --beta/--rc select matching pre-releases)
+get_latest_version() {
+    local include_beta="$1"
+    local include_rc="$2"
+
+    # Default path: stable-only
+    if [[ "$include_beta" != "true" && "$include_rc" != "true" ]]; then
+        get_latest_release
+        return
+    fi
+
+    print_info "Fetching releases to determine latest version (beta=${include_beta}, rc=${include_rc})..."
+
+    local json tag_name pattern
+    tag_name=""
+    if [[ "$include_beta" == "true" && "$include_rc" == "true" ]]; then
+        pattern='-beta|-rc'
+    elif [[ "$include_beta" == "true" ]]; then
+        pattern='-beta'
+    else
+        pattern='-rc'
+    fi
+
+    if json=$(curl_gh "${GITHUB_API}/releases?per_page=100" 2>/dev/null); then
+        local tags pairs
+        if command -v jq >/dev/null 2>&1; then
+            tags=$(echo "$json" | jq -r '.[] | select(.draft==false) | .tag_name')
+        else
+            tags=$(echo "$json" | grep -oE '"tag_name"\s*:\s*"[^"]+"' | sed -E 's/.*"tag_name"\s*:\s*"([^"]+)".*/\1/')
+        fi
+
+        debug "Fetched release tags (first 20): $(printf '%s\n' "$tags" | head -n20 | tr '\n' ' ')"
+
+        # Build pairs of cleaned|original, where cleaned strips any prefix before the semantic version
+        pairs=$(printf '%s\n' "$tags" | awk '{
+            orig=$0;
+            cleaned=orig;
+            if (match(cleaned,/(v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z\.\-]+)*)$/,m)) {
+                cleaned=m[1];
+            }
+            print cleaned"|"orig
+        }')
+
+        # Filter by pattern on the cleaned part and semver-sort to pick the highest; return original tag
+        local best
+        best=$(printf '%s\n' "$pairs" |
+            awk -F'|' -v pat="$pattern" '$1 ~ pat {print $0}' |
+            awk -F'|' '{ t=$1; sub(/^v/,"",t); print t"|"$2 }' |
+            sort -t '|' -k1,1V | tail -n1 | cut -d'|' -f2)
+
+        tag_name="$best"
+    fi
+
+    if [[ -z "$tag_name" ]]; then
+        print_warning "No matching pre-release found; falling back to latest stable release."
+        tag_name=$(get_latest_release)
+    fi
+
+    echo "$tag_name"
+}
+
+# Normalize version by removing a leading 'v'
+normalize_version() {
+    local v="$1"
+    v="${v#v}"
+    echo "$v"
+}
+
+# Return 0 (true) if $1 < $2 in semantic version order, using sort -V
+version_lt() {
+    local a b first
+    a=$(normalize_version "$1")
+    b=$(normalize_version "$2")
+    first=$(printf '%s\n' "$a" "$b" | sort -V | head -n1)
+    [[ "$first" == "$a" && "$a" != "$b" ]]
+}
+
+# Get asset download url for a given version and platform (e.g., darwin_arm64), prefer .zip
+get_asset_download_url() {
+    local version=$1
+    local platform=$2
+    local url=""
+    
+    print_info "Resolving asset download URL for ${version} (${platform})..."
+    debug "Querying ${GITHUB_API}/releases/tags/${version}"
+    if json=$(curl_gh "${GITHUB_API}/releases/tags/${version}" 2>/dev/null); then
+        if command -v jq >/dev/null 2>&1; then
+            debug "Assets on tag (names): $(echo "$json" | jq -r '.assets[]?.name' | tr '\n' ' ')"
+            url=$(echo "$json" | jq -r --arg platform "$platform" '.assets[]?.browser_download_url | select(test($platform)) | select(endswith(".zip"))' | head -n1)
+        else
+            url=$(echo "$json" \
+                | tr -d '\n\r\t' \
+                | sed -nE 's/.*("browser_download_url"[[[:space:]]]*:[[:space:]]*"[^"]+").*/\1/p' \
+                | sed -nE 's/.*"browser_download_url"[[[:space:]]]*:[[:space:]]*"([^"]+)".*/\1/p' \
+                | grep "$platform" \
+                | grep '\.zip$' -m 1)
+        fi
+    fi
+    debug "Matched asset URL from tag endpoint: ${url:-<none>}"
+
+    # Fallback to patterned URL if API failed or empty
+    if [[ -z "$url" ]]; then
+        print_warning "API failed or no asset matched; trying list endpoint..."
+        if json2=$(curl_gh "${GITHUB_API}/releases?per_page=100" 2>/dev/null); then
+            if command -v jq >/dev/null 2>&1; then
+                url=$(echo "$json2" | jq -r --arg tag "$version" --arg platform "$platform" '.[] | select(.tag_name==$tag) | .assets[]?.browser_download_url | select(test($platform)) | select(endswith(".zip"))' | head -n1)
+            else
+                url=$(echo "$json2" \
+                    | tr -d '\n\r\t' \
+                    | sed -nE 's/.*\{([^}]*)\}.*/\{\1\}/gp' \
+                    | grep -E '"tag_name"[[:space:]]*:[[:space:]]*"'"$version"'"' \
+                    | sed -nE 's/.*("browser_download_url"[[[:space:]]]*:[[:space:]]*"[^"]+").*/\1/p' \
+                    | sed -nE 's/.*"browser_download_url"[[[:space:]]]*:[[:space:]]*"([^"]+)".*/\1/p' \
+                    | grep "$platform" \
+                    | grep '\.zip$' -m 1)
+            fi
+        fi
+        debug "Matched asset URL from list endpoint: ${url:-<none>}"
+    fi
+
+    if [[ -z "$url" ]]; then
+        print_warning "API failed or no asset matched; trying patterned URL..."
+        local clean_version="$version"
+        clean_version="${clean_version##*:}"
+        clean_version="${clean_version#v}"
+        local filename="axonhub_${clean_version}_${platform}.zip"
+        local candidate="https://github.com/${REPO}/releases/download/${version}/${filename}"
+        debug "Trying candidate URL: $candidate"
+        if curl -fsI "$candidate" >/dev/null 2>&1; then
+            url="$candidate"
+        fi
+    fi
+    
+    if [[ -z "$url" ]]; then
+        print_error "Could not find a matching .zip asset for platform ${platform} in release ${version}"
+        exit 1
+    fi
+    echo "$url"
+}
+
+download_and_extract() {
+    local version=$1
+    local platform=$2
+    local temp_dir=$(mktemp -d)
+    
+    # Resolve exact asset URL from GitHub API
+    local download_url
+    download_url=$(get_asset_download_url "$version" "$platform")
+    local filename
+    filename=$(basename "$download_url")
+    
+    print_info "Downloading AxonHub ${version} for ${platform}..."
+    
+    if ! curl -fSL -o "${temp_dir}/${filename}" "$download_url"; then
+        print_error "Failed to download AxonHub asset"
+        rm -rf "$temp_dir"
+        exit 1
+    fi
+    
+    print_info "Extracting archive..."
+    
+    if ! command -v unzip >/dev/null 2>&1; then
+        print_error "unzip command not found. Please install unzip and rerun."
+        rm -rf "$temp_dir"
+        exit 1
+    fi
+    
+    if ! unzip -q "${temp_dir}/${filename}" -d "$temp_dir"; then
+        print_error "Failed to extract archive"
+        rm -rf "$temp_dir"
+        exit 1
+    fi
+    
+    # Find the extracted binary
+    local binary_path
+    binary_path=$(find "$temp_dir" -name "axonhub" -type f | head -1)
+    
+    if [[ -z "$binary_path" ]]; then
+        print_error "Could not find axonhub binary in archive"
+        rm -rf "$temp_dir"
+        exit 1
+    fi
+    
+    echo "$binary_path"
+}
+
+create_user() {
+    # No system user management per requirements
+    print_info "Skipping system user creation"
+}
+
+setup_directories() {
+    print_info "Setting up directories..."
+    
+    # Create directories
+    mkdir -p "$CONFIG_DIR" "$DATA_DIR" "$LOG_DIR"
+    
+    # Set ownership and permissions to invoking user
+    local target_user="${SUDO_USER:-$USER}"
+    local target_group
+    target_group="$(id -gn "$target_user" 2>/dev/null || echo "$target_user")"
+    chown -R "$target_user:$target_group" "$CONFIG_DIR" "$DATA_DIR" "$LOG_DIR" 2>/dev/null || true
+    chmod 755 "$CONFIG_DIR" "$DATA_DIR" "$LOG_DIR"
+}
+
+install_binary() {
+    local binary_path=$1
+    
+    print_info "Installing AxonHub binary to $INSTALL_DIR..."
+    
+    # Install binary
+    cp "$binary_path" "$INSTALL_DIR/axonhub"
+    chmod +x "$INSTALL_DIR/axonhub"
+    
+    # Clean up temp directory only if it looks like a system temp path
+    local dir
+    dir="$(dirname "$binary_path")"
+    local tmp1="${TMPDIR:-/tmp}"
+    if [[ "$dir" == /tmp/* || "$dir" == /var/folders/* || "$dir" == /private/var/folders/* || "$dir" == "$tmp1"* ]]; then
+        rm -rf "$dir" 2>/dev/null || true
+    fi
+}
+
+create_default_config() {
+    local config_file="$CONFIG_DIR/config.yml"
+    
+    if [[ ! -f "$config_file" ]]; then
+        print_info "Creating default configuration..."
+        
+        cat > "$config_file" << EOF
+server:
+  port: 8090
+  name: "AxonHub"
+  debug: false
+
+db:
+  dialect: "sqlite3"
+  dsn: "${BASE_DIR}/axonhub.db?cache=shared&_fk=1&journal_mode=WAL"
+
+cache:
+  mode: "memory"
+  cache:
+    expiration: "5s" 
+    cleanup_interval: "5s"
+
+log:
+  level: "info"
+  encoding: "json"
+  output: "file"
+  file:
+    path: "${BASE_DIR}/logs/axonhub.log"
+    max_size: 100
+    max_age: 30
+    max_backups: 10
+    local_time: true
+EOF
+        
+        local target_user="${SUDO_USER:-$USER}"
+        local target_group
+        target_group="$(id -gn "$target_user" 2>/dev/null || echo "$target_user")"
+        chown "$target_user:$target_group" "$config_file" 2>/dev/null || true
+        chmod 644 "$config_file"
+        
+        print_success "Default configuration created at $config_file"
+    else
+        print_info "Configuration file already exists at $config_file"
+    fi
+}
+
+# Note: systemd service installation removed; use deploy/start.sh and deploy/stop.sh to manage AxonHub
+
+main() {
+    print_info "Starting AxonHub installation..."
+    
+    # Check if running as root
+    check_root
+    
+    # Detect system architecture
+    local platform
+    platform=$(detect_architecture)
+    print_info "Detected platform: $platform"
+    
+    # Determine target version (env AXONHUB_VERSION, positional arg, or latest)
+    local version version_arg
+    version="${AXONHUB_VERSION:-}"
+
+    # Parse CLI flags and optional version argument
+    if [[ -z "$version" ]]; then
+        while [[ $# -gt 0 ]]; do
+            case "$1" in
+                -b|--beta)
+                    INCLUDE_BETA="true"; shift ;;
+                -r|--rc)
+                    INCLUDE_RC="true"; shift ;;
+                -v|--verbose)
+                    VERBOSE="true"; shift ;;
+                -h|--help)
+                    usage; exit 0 ;;
+                --)
+                    shift; break ;;
+                -*)
+                    print_error "Unknown option: $1"; usage; exit 1 ;;
+                *)
+                    if [[ -z "${version_arg:-}" ]]; then
+                        version_arg="$1"; shift
+                    else
+                        break
+                    fi ;;
+            esac
+        done
+        version="${version_arg:-}"
+    fi
+
+    if [[ -z "$version" ]]; then
+        version=$(get_latest_version "$INCLUDE_BETA" "$INCLUDE_RC")
+    fi
+    print_info "Using version: $version"
+    
+    # Prefer local binary near this script; offer to update if newer is available
+    local binary_path
+    local script_dir
+    script_dir=$(cd "$(dirname "$0")" && pwd)
+    if [[ -x "$script_dir/axonhub" ]]; then
+        print_info "Found local binary: $script_dir/axonhub"
+        # Try to read local version from the binary
+        local local_version norm_local norm_target
+        if local_version=$("$script_dir/axonhub" version 2>/dev/null | head -n1 | tr -d '\r'); then
+            print_info "Local binary version: $local_version"
+            norm_local=$(normalize_version "$local_version")
+        else
+            print_warning "Could not determine local binary version"
+            norm_local=""
+        fi
+        norm_target=$(normalize_version "$version")
+
+        if [[ -n "$norm_local" && "$norm_local" != "dev" ]] && version_lt "$norm_local" "$norm_target"; then
+            echo -n "A newer version is available (local ${local_version}, latest ${version}). Download the latest now? [Y/n]: " 1>&2
+            read -r reply
+            if [[ -z "$reply" || "$reply" =~ ^[Yy]$ ]]; then
+                binary_path=$(download_and_extract "$version" "$platform")
+            else
+                print_info "Using existing local binary as requested."
+                binary_path="$script_dir/axonhub"
+            fi
+        else
+            print_info "Local binary is up-to-date. Using existing local binary."
+            binary_path="$script_dir/axonhub"
+        fi
+    else
+        # Download and extract
+        binary_path=$(download_and_extract "$version" "$platform")
+    fi
+    
+    # Create system user
+    create_user
+    
+    # Setup directories
+    setup_directories
+    
+    # Install binary
+    install_binary "$binary_path"
+    
+    # Create default configuration
+    create_default_config
+    
+    print_success "AxonHub installation completed!"
+    echo
+    
+    # Get configured port for display
+    local port=8090
+    if [[ -x "$INSTALL_DIR/axonhub" ]]; then
+        local config_port
+        config_port=$("$INSTALL_DIR/axonhub" config get server.port 2>/dev/null) || true
+        if [[ -n "$config_port" && "$config_port" =~ ^[0-9]+$ ]]; then
+            port="$config_port"
+        fi
+    fi
+    
+    print_info "Next steps:"
+    echo "  1. Edit configuration: nano $CONFIG_DIR/config.yml"
+    echo "  2. Start AxonHub: ./start.sh"
+    echo "  3. Stop AxonHub: ./stop.sh"
+    echo "  4. View logs: tail -f $LOG_DIR/axonhub.log"
+    echo "  5. Access web interface: http://localhost:${port}"
+    echo
+    print_info "To start AxonHub now, run: ./start.sh"
+}
+
+# Run main function
+main "$@"

deploy/nginx.conf

@@ -0,0 +1,238 @@
+# AxonHub Nginx 配置文件
+# 用于 Docker 部署的反向代理配置
+
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 1024;
+    use epoll;
+    multi_accept on;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # 日志格式
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for" '
+                    'rt=$request_time uct="$upstream_connect_time" '
+                    'uht="$upstream_header_time" urt="$upstream_response_time"';
+
+    access_log /var/log/nginx/access.log main;
+
+    # 基础配置
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 2048;
+    server_tokens off;
+
+    # Gzip 压缩
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types
+        text/plain
+        text/css
+        text/xml
+        text/javascript
+        application/json
+        application/javascript
+        application/xml+rss
+        application/atom+xml
+        image/svg+xml;
+
+    # 上游服务器配置
+    upstream axonhub_backend {
+        server axonhub:8090;
+        keepalive 32;
+    }
+
+    # 限流配置
+    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
+
+    # HTTP 服务器（重定向到 HTTPS）
+    server {
+        listen 80;
+        server_name _;
+        
+        # 健康检查端点
+        location /health {
+            access_log off;
+            return 200 "healthy\n";
+            add_header Content-Type text/plain;
+        }
+        
+        # 重定向到 HTTPS
+        location / {
+            return 301 https://$host$request_uri;
+        }
+    }
+
+    # HTTPS 服务器
+    server {
+        listen 443 ssl http2;
+        server_name _;
+
+        # SSL 配置
+        ssl_certificate /etc/nginx/ssl/cert.pem;
+        ssl_certificate_key /etc/nginx/ssl/key.pem;
+        
+        # SSL 安全配置
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
+        ssl_prefer_server_ciphers off;
+        ssl_session_cache shared:SSL:10m;
+        ssl_session_timeout 10m;
+        
+        # 安全头
+        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+        add_header X-Frame-Options DENY always;
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+        # 主要代理配置
+        location / {
+            # 限流
+            limit_req zone=api burst=20 nodelay;
+            
+            # 代理设置
+            proxy_pass http://axonhub_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+            
+            # 超时设置
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 60s;
+            proxy_read_timeout 60s;
+            
+            # 缓冲设置
+            proxy_buffering on;
+            proxy_buffer_size 4k;
+            proxy_buffers 8 4k;
+            proxy_busy_buffers_size 8k;
+        }
+
+        # API 端点特殊配置
+        location /v1/ {
+            # API 限流
+            limit_req zone=api burst=50 nodelay;
+            
+            proxy_pass http://axonhub_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            
+            # 长时间请求支持（AI 生成可能需要更长时间）
+            proxy_connect_timeout 120s;
+            proxy_send_timeout 120s;
+            proxy_read_timeout 600s;
+            
+            # 禁用缓冲以支持流式响应
+            proxy_buffering off;
+            proxy_cache off;
+        }
+
+        # GraphQL 端点
+        location /query {
+            limit_req zone=api burst=30 nodelay;
+            
+            proxy_pass http://axonhub_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            
+            # GraphQL 通常需要较长的处理时间
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 60s;
+            proxy_read_timeout 300s;
+        }
+
+        # 登录端点限流
+        location /auth/login {
+            limit_req zone=login burst=5 nodelay;
+            
+            proxy_pass http://axonhub_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # 静态文件缓存
+        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+            proxy_pass http://axonhub_backend;
+            proxy_set_header Host $host;
+            
+            # 缓存设置
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+            add_header Vary Accept-Encoding;
+            
+            # 压缩
+            gzip_static on;
+        }
+
+        # 健康检查
+        location /health {
+            access_log off;
+            proxy_pass http://axonhub_backend/health;
+            proxy_set_header Host $host;
+            
+            # 快速超时
+            proxy_connect_timeout 5s;
+            proxy_send_timeout 5s;
+            proxy_read_timeout 5s;
+        }
+
+        # 监控端点（可选，需要认证）
+        location /metrics {
+            # 限制访问
+            allow 127.0.0.1;
+            allow 10.0.0.0/8;
+            allow 172.16.0.0/12;
+            allow 192.168.0.0/16;
+            deny all;
+            
+            proxy_pass http://axonhub_backend/metrics;
+            proxy_set_header Host $host;
+        }
+
+        # 禁止访问敏感文件
+        location ~ /\. {
+            deny all;
+            access_log off;
+            log_not_found off;
+        }
+        
+        location ~ \.(yml|yaml|json|env)$ {
+            deny all;
+            access_log off;
+            log_not_found off;
+        }
+    }
+}

deploy/start.bat

@@ -0,0 +1,14 @@
+@echo off
+setlocal
+
+REM AxonHub Windows start wrapper (.bat)
+
+where powershell >NUL 2>NUL
+if %ERRORLEVEL% NEQ 0 (
+  echo [ERROR] PowerShell is required to run this script.
+  exit /b 1
+)
+
+set "SCRIPT_DIR=%~dp0"
+powershell -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%start.ps1" %*
+exit /b %ERRORLEVEL%

deploy/start.ps1

@@ -0,0 +1,155 @@
+param(
+    [Parameter(ValueFromRemainingArguments=$true)]
+    [string[]]$ArgsFromCmd
+)
+
+$ErrorActionPreference = 'Stop'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+function Write-Info([string]$m){ Write-Host "[INFO] $m" -ForegroundColor Cyan }
+function Write-Success([string]$m){ Write-Host "[SUCCESS] $m" -ForegroundColor Green }
+function Write-Warn([string]$m){ Write-Host "[WARNING] $m" -ForegroundColor Yellow }
+function Write-Err([string]$m){ Write-Host "[ERROR] $m" -ForegroundColor Red }
+
+$ServiceName = 'axonhub'
+$BaseDir = Join-Path $env:LOCALAPPDATA 'AxonHub'
+$ConfigFile = Join-Path $BaseDir 'config.yml'
+$BinaryPath = Join-Path $BaseDir 'axonhub.exe'
+$PidFile = Join-Path $BaseDir 'axonhub.pid'
+$LogFile = Join-Path $BaseDir 'axonhub.log'
+$DefaultPort = 8090
+
+function Show-Usage {
+  Write-Host @" 
+Usage: start.bat
+
+This script starts AxonHub directly (no service manager).
+Logs: $LogFile
+PID file: $PidFile
+"@
+}
+
+foreach($a in $ArgsFromCmd){
+  switch -Regex ($a){
+    '^(--help|-h)$' { Show-Usage; exit 0 }
+    default { Write-Warn "Unknown option: $a" }
+  }
+}
+
+function Ensure-Dirs([string]$path){ if(-not (Test-Path $path)){ New-Item -ItemType Directory -Force -Path $path | Out-Null } }
+
+function Get-ConfiguredPort {
+  $port = $DefaultPort
+  if(Test-Path $BinaryPath){
+    try {
+      $configPort = $null
+      $configPort = & $BinaryPath config get server.port 2>$null
+      if($configPort -match '^[0-9]+$'){
+        $port = [int]$configPort
+      }
+    } catch {}
+  }
+  return $port
+}
+
+function Check-Port([int]$port){
+  try {
+    $lines = netstat -ano | Select-String -Pattern "^\s*TCP\s+[^:]+:$port\s+" -ErrorAction SilentlyContinue
+    if($lines){
+      Write-Warn "Port $port is already in use"
+      Write-Info "Processes using port ${port}:"
+      $lines | ForEach-Object { $_.Line } | Write-Host
+      return $false
+    }
+  } catch {}
+  return $true
+}
+
+$stdoutTempFile = Join-Path $env:TEMP ("axonhub-" + [guid]::NewGuid().ToString() + '-stdout.log')
+$stderrTempFile = Join-Path $env:TEMP ("axonhub-" + [guid]::NewGuid().ToString() + '-stderr.log')
+
+Write-Info 'Starting AxonHub...'
+
+if(-not (Test-Path $BinaryPath)){
+  Write-Err "AxonHub binary not found at $BinaryPath"
+  Write-Info 'Please run the installer first: install.bat'
+  exit 1
+}
+
+Ensure-Dirs $BaseDir
+
+# Already running?
+if(Test-Path $PidFile){
+  try {
+    $pid = Get-Content -Path $PidFile -ErrorAction Stop
+    if($pid -and (Get-Process -Id $pid -ErrorAction SilentlyContinue)){
+      Write-Warn "AxonHub is already running (PID: $pid)"
+      exit 0
+    } else {
+      Write-Info 'Removing stale PID file'
+      Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    }
+  } catch {
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+  }
+}
+
+# Check configured port
+$port = Get-ConfiguredPort
+if(-not (Check-Port $port)){
+  Write-Err "Cannot start AxonHub: port $port is already in use"
+  exit 1
+}
+
+$ConfigArgs = @()
+if(Test-Path $ConfigFile){ 
+  # Config exists, binary will auto-detect it from $HOME/.config/axonhub/
+  Write-Info "Configuration found at $ConfigFile, binary will auto-detect it" 
+} else { 
+  Write-Warn "Configuration not found at $ConfigFile, starting with defaults" 
+}
+
+Write-Info 'Starting AxonHub process...'
+try {
+  if($ConfigArgs.Count -gt 0){
+    $p = Start-Process -FilePath $BinaryPath -ArgumentList $ConfigArgs -RedirectStandardOutput $stdoutTempFile -RedirectStandardError $stderrTempFile -PassThru -WindowStyle Hidden
+  } else {
+    $p = Start-Process -FilePath $BinaryPath -RedirectStandardOutput $stdoutTempFile -RedirectStandardError $stderrTempFile -PassThru -WindowStyle Hidden
+  }
+  Start-Sleep -Seconds 2
+  if($p -and (Get-Process -Id $p.Id -ErrorAction SilentlyContinue)){
+    $p.Id | Out-File -FilePath $PidFile -Encoding ascii -Force
+    Remove-Item -Force $stdoutTempFile,$stderrTempFile -ErrorAction SilentlyContinue
+    Write-Success "AxonHub started successfully (PID: $($p.Id))"
+    Write-Info 'Process information:'
+    Write-Host "  • PID: $($p.Id)"
+    Write-Host "  • Log file: $LogFile"
+    Write-Host "  • Config: " -NoNewline; if(Test-Path $ConfigFile){ Write-Host $ConfigFile } else { Write-Host 'default' }
+    Write-Host "  • Web interface: http://localhost:$port"
+    Write-Host ''
+    Write-Info 'To stop AxonHub: stop.bat'
+    Write-Info "To view logs: Get-Content -Path '$LogFile' -Tail 100 -Wait"
+  } else {
+    Write-Err 'AxonHub failed to start'
+    if(Test-Path $LogFile){
+      Write-Info 'Last few log lines:'
+      Get-Content -Path $LogFile -Tail 20
+    }
+    if(Test-Path $stdoutTempFile){
+      Write-Info 'Captured stdout:'
+      Get-Content -Path $stdoutTempFile -Tail 20
+    }
+    if(Test-Path $stderrTempFile){
+      Write-Info 'Captured stderr:'
+      Get-Content -Path $stderrTempFile -Tail 20
+    }
+    if(Test-Path $PidFile){ Remove-Item -Force $PidFile -ErrorAction SilentlyContinue }
+    Remove-Item -Force $stdoutTempFile,$stderrTempFile -ErrorAction SilentlyContinue
+    exit 1
+  }
+} catch {
+  Write-Err $_.Exception.Message
+  if(Test-Path $PidFile){ Remove-Item -Force $PidFile -ErrorAction SilentlyContinue }
+  Remove-Item -Force $stdoutTempFile,$stderrTempFile -ErrorAction SilentlyContinue
+  exit 1
+}

deploy/start.sh

@@ -0,0 +1,200 @@
+#!/bin/bash
+
+# AxonHub Start Script
+# This script starts AxonHub directly (no systemd), with proper error handling and logging
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+SERVICE_NAME="axonhub"
+# Resolve non-root user's HOME when running via sudo
+if [[ -n "$SUDO_USER" && "$SUDO_USER" != "root" ]]; then
+    USER_HOME="$(eval echo ~${SUDO_USER})"
+    TARGET_USER="$SUDO_USER"
+else
+    USER_HOME="$HOME"
+    TARGET_USER="$USER"
+fi
+TARGET_GROUP="$(id -gn "$TARGET_USER" 2>/dev/null || echo "$TARGET_USER")"
+BASE_DIR="${USER_HOME}/.config/axonhub"
+CONFIG_FILE="${BASE_DIR}/config.yml"
+BINARY_PATH="/usr/local/bin/axonhub"
+DEFAULT_PORT=8090
+PID_FILE="${BASE_DIR}/axonhub.pid"
+LOG_FILE="${BASE_DIR}/axonhub.log"
+
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Note: systemd-related logic removed for simplicity; this script always starts directly
+
+start_directly() {
+    print_info "Starting AxonHub directly..."
+    
+    # Check if already running
+    if [[ -f "$PID_FILE" ]]; then
+        local pid=$(cat "$PID_FILE")
+        if kill -0 "$pid" 2>/dev/null; then
+            print_warning "AxonHub is already running (PID: $pid)"
+            return 0
+        else
+            print_info "Removing stale PID file"
+            rm -f "$PID_FILE"
+        fi
+    fi
+    
+    # Check if binary exists
+    if [[ ! -x "$BINARY_PATH" ]]; then
+        print_error "AxonHub binary not found at $BINARY_PATH"
+        print_info "Please run the install script first: ./deploy/install.sh"
+        return 1
+    fi
+    
+    # Check if config exists
+    if [[ ! -f "$CONFIG_FILE" ]]; then
+        print_warning "Configuration file not found at $CONFIG_FILE"
+        print_info "Starting with default configuration..."
+        CONFIG_ARGS=""
+    else
+        # Config exists, binary will auto-detect it from $HOME/.config/axonhub/
+        CONFIG_ARGS=""
+    fi
+    
+    # Ensure base directory exists and is owned by target user
+    mkdir -p "$BASE_DIR"
+    chown "$TARGET_USER:$TARGET_GROUP" "$BASE_DIR" 2>/dev/null || true
+    
+    # Start AxonHub in background
+    print_info "Starting AxonHub process..."
+    
+    if [[ $EUID -eq 0 ]]; then
+        # Running with sudo/root; start as invoking user so files live under their HOME
+        print_info "Running as user: $TARGET_USER"
+        sudo -u "$TARGET_USER" bash -c "mkdir -p '$BASE_DIR'; \"$BINARY_PATH\" $CONFIG_ARGS >> '$LOG_FILE' 2>&1 & echo \$! > '$PID_FILE'"
+        local pid
+        pid=$(cat "$PID_FILE" 2>/dev/null || true)
+    else
+        "$BINARY_PATH" $CONFIG_ARGS > "$LOG_FILE" 2>&1 &
+        local pid=$!
+        echo "$pid" > "$PID_FILE"
+    fi
+    
+    # Wait a moment and check if process is still running
+    sleep 2
+    
+    if kill -0 "$pid" 2>/dev/null; then
+        print_success "AxonHub started successfully (PID: $pid)"
+        print_info "Process information:"
+        echo "  • PID: $pid"
+        echo "  • Log file: $LOG_FILE"
+        echo "  • Config: ${CONFIG_FILE:-"default"}"
+        local port
+        port=$(get_configured_port)
+        echo "  • Web interface: http://localhost:${port}"
+        echo
+        print_info "To stop AxonHub: ./stop.sh"
+        print_info "To view logs: tail -f $LOG_FILE"
+    else
+        print_error "AxonHub failed to start"
+        if [[ -f "$LOG_FILE" ]]; then
+            print_info "Last few log lines:"
+            tail -n 10 "$LOG_FILE"
+        fi
+        rm -f "$PID_FILE"
+        return 1
+    fi
+}
+
+get_configured_port() {
+    local port="$DEFAULT_PORT"
+    
+    # Try to get port from config using axonhub binary
+    if [[ -x "$BINARY_PATH" ]]; then
+        local config_port
+        config_port=$("$BINARY_PATH" config get server.port 2>/dev/null) || true
+        if [[ -n "$config_port" && "$config_port" =~ ^[0-9]+$ ]]; then
+            port="$config_port"
+        fi
+    fi
+    
+    echo "$port"
+}
+
+check_port() {
+    local port=${1:-$DEFAULT_PORT}
+    
+    if command -v netstat >/dev/null 2>&1; then
+        if netstat -tuln | grep -q ":$port "; then
+            print_warning "Port $port is already in use"
+            print_info "Processes using port $port:"
+            netstat -tulnp | grep ":$port " || true
+            return 1
+        fi
+    elif command -v ss >/dev/null 2>&1; then
+        if ss -tuln | grep -q ":$port "; then
+            print_warning "Port $port is already in use"
+            print_info "Processes using port $port:"
+            ss -tulnp | grep ":$port " || true
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+main() {
+    print_info "Starting AxonHub..."
+    
+    # Get configured port
+    local port
+    port=$(get_configured_port)
+    
+    # Check if port is available
+    if ! check_port "$port"; then
+        print_error "Cannot start AxonHub: port $port is already in use"
+        return 1
+    fi
+    
+    # Always start directly
+    start_directly
+}
+
+# Handle script arguments
+case "${1:-}" in
+    --help|-h)
+        echo "Usage: $0"
+        echo
+        echo "This script starts AxonHub directly (no systemd)."
+        echo "Logs: $LOG_FILE"
+        echo "PID file: $PID_FILE"
+        exit 0
+        ;;
+    "")
+        main
+        ;;
+    *)
+        print_error "Unknown option: $1"
+        print_info "Use --help for usage information"
+        exit 1
+        ;;
+esac

deploy/stop.bat

@@ -0,0 +1,14 @@
+@echo off
+setlocal
+
+REM AxonHub Windows stop wrapper (.bat)
+
+where powershell >NUL 2>NUL
+if %ERRORLEVEL% NEQ 0 (
+  echo [ERROR] PowerShell is required to run this script.
+  exit /b 1
+)
+
+set "SCRIPT_DIR=%~dp0"
+powershell -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%stop.ps1" %*
+exit /b %ERRORLEVEL%

deploy/stop.ps1

@@ -0,0 +1,163 @@
+param(
+    [Parameter(ValueFromRemainingArguments=$true)]
+    [string[]]$ArgsFromCmd
+)
+
+$ErrorActionPreference = 'Stop'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+function Write-Info([string]$m){ Write-Host "[INFO] $m" -ForegroundColor Cyan }
+function Write-Success([string]$m){ Write-Host "[SUCCESS] $m" -ForegroundColor Green }
+function Write-Warn([string]$m){ Write-Host "[WARNING] $m" -ForegroundColor Yellow }
+function Write-Err([string]$m){ Write-Host "[ERROR] $m" -ForegroundColor Red }
+
+$ServiceName = 'axonhub'
+$BaseDir = Join-Path $env:LOCALAPPDATA 'AxonHub'
+$PidFile = Join-Path $BaseDir 'axonhub.pid'
+$ProcessName = 'axonhub'
+
+function Show-Usage {
+  Write-Host @" 
+Usage: stop.bat [--force]
+
+This script stops AxonHub directly (no service manager).
+Options:
+  --force     Force kill all AxonHub processes
+  --help, -h  Show this help message
+"@
+}
+
+$Force = $false
+foreach($a in $ArgsFromCmd){
+  switch -Regex ($a){
+    '^(--force)$' { $Force = $true; continue }
+    '^(--help|-h)$' { Show-Usage; exit 0 }
+    default { Write-Warn "Unknown option: $a" }
+  }
+}
+
+function Stop-ByPid(){
+  Write-Info 'Stopping AxonHub using PID file...'
+  if(-not (Test-Path $PidFile)){
+    Write-Warn "PID file not found at $PidFile"
+    return $false
+  }
+  try {
+    $pid = Get-Content -Path $PidFile -ErrorAction Stop
+  } catch {
+    Write-Warn 'Unable to read PID file'
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    return $false
+  }
+  if(-not ($pid -match '^[0-9]+$')){
+    Write-Err "Invalid PID in file: $pid"
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    return $false
+  }
+  $proc = Get-Process -Id $pid -ErrorAction SilentlyContinue
+  if(-not $proc){
+    Write-Warn "Process with PID $pid is not running"
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    return $false
+  }
+  Write-Info "Stopping process $pid ..."
+  try { Stop-Process -Id $pid -ErrorAction SilentlyContinue } catch {}
+  # Wait up to 10 seconds
+  $timeout = 10
+  for($i=0; $i -lt $timeout; $i++){
+    Start-Sleep -Seconds 1
+    if(-not (Get-Process -Id $pid -ErrorAction SilentlyContinue)){ break }
+  }
+  if(Get-Process -Id $pid -ErrorAction SilentlyContinue){
+    Write-Warn 'Process did not stop gracefully, forcing termination...'
+    try { Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue } catch {}
+    Start-Sleep -Seconds 2
+  }
+  if(-not (Get-Process -Id $pid -ErrorAction SilentlyContinue)){
+    Write-Success "AxonHub stopped successfully (PID: $pid)"
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    return $true
+  } else {
+    Write-Err 'Failed to stop AxonHub process'
+    return $false
+  }
+}
+
+function Stop-ByProcessName(){
+  Write-Info 'Stopping AxonHub by process name...'
+  $procs = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^axonhub' }
+  if(-not $procs){
+    Write-Warn 'No AxonHub processes found'
+    return $false
+  }
+  Write-Info ("Found AxonHub processes: " + ($procs.Id -join ' '))
+  foreach($p in $procs){
+    Write-Info ("Stopping process " + $p.Id + ' ...')
+    try { Stop-Process -Id $p.Id -ErrorAction SilentlyContinue } catch {}
+    # Wait up to 10 seconds each
+    $timeout = 10
+    for($i=0; $i -lt $timeout; $i++){
+      Start-Sleep -Seconds 1
+      if(-not (Get-Process -Id $p.Id -ErrorAction SilentlyContinue)){ break }
+    }
+    if(Get-Process -Id $p.Id -ErrorAction SilentlyContinue){
+      Write-Warn ("Process " + $p.Id + ' did not stop gracefully, forcing...')
+      try { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue } catch {}
+    }
+  }
+  Start-Sleep -Seconds 2
+  $remaining = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^axonhub' }
+  if(-not $remaining){
+    Write-Success 'All AxonHub processes stopped successfully'
+    Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    return $true
+  } else {
+    Write-Err ("Some AxonHub processes are still running: " + ($remaining.Id -join ' '))
+    return $false
+  }
+}
+
+function Check-Running(){
+  $procs = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^axonhub' }
+  if($procs){
+    Write-Info 'Running AxonHub processes:'
+    $procs | Select-Object Id,ProcessName,Path | Format-Table -AutoSize | Out-String | Write-Host
+    return $true
+  }
+  return $false
+}
+
+if($Force){
+  Write-Info 'Force stopping all AxonHub processes...'
+  $procs = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^axonhub' }
+  if($procs){
+    foreach($p in $procs){ try { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue } catch {} }
+    Start-Sleep -Seconds 2
+    $still = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^axonhub' }
+    if(-not $still){
+      Write-Success 'All AxonHub processes force-stopped'
+      Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+    } else {
+      Write-Err 'Failed to force-stop some processes'
+      exit 1
+    }
+  } else {
+    Write-Info 'No AxonHub processes found'
+  }
+  exit 0
+}
+
+Write-Info 'Stopping AxonHub...'
+$stopped = $false
+if(Stop-ByPid){ $stopped = $true }
+if(-not $stopped){ if(Stop-ByProcessName){ $stopped = $true } }
+if(-not $stopped){
+  if(Check-Running){
+    Write-Err 'Failed to stop all AxonHub processes'
+    exit 1
+  } else {
+    Write-Info 'No AxonHub processes were running'
+  }
+}
+Remove-Item -Force $PidFile -ErrorAction SilentlyContinue
+Write-Success 'AxonHub has been stopped'

deploy/stop.sh

@@ -0,0 +1,226 @@
+#!/bin/bash
+
+# AxonHub Stop Script
+# This script stops AxonHub directly (no systemd), with proper error handling
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+SERVICE_NAME="axonhub"
+# Resolve non-root user's HOME when running via sudo
+if [[ -n "$SUDO_USER" && "$SUDO_USER" != "root" ]]; then
+    USER_HOME="$(eval echo ~${SUDO_USER})"
+else
+    USER_HOME="$HOME"
+fi
+BASE_DIR="${USER_HOME}/.config/axonhub"
+PID_FILE="${BASE_DIR}/axonhub.pid"
+PROCESS_NAME="axonhub"
+
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Note: systemd-related logic removed for simplicity; this script always stops directly
+
+stop_by_pid() {
+    print_info "Stopping AxonHub using PID file..."
+    
+    if [[ ! -f "$PID_FILE" ]]; then
+        print_warning "PID file not found at $PID_FILE"
+        return 1
+    fi
+    
+    local pid=$(cat "$PID_FILE")
+    
+    if [[ ! "$pid" =~ ^[0-9]+$ ]]; then
+        print_error "Invalid PID in file: $pid"
+        rm -f "$PID_FILE"
+        return 1
+    fi
+    
+    if ! kill -0 "$pid" 2>/dev/null; then
+        print_warning "Process with PID $pid is not running"
+        rm -f "$PID_FILE"
+        return 1
+    fi
+    
+    print_info "Sending SIGTERM to process $pid..."
+    if kill -TERM "$pid" 2>/dev/null; then
+        # Wait for graceful shutdown
+        local timeout=10
+        local count=0
+        
+        while kill -0 "$pid" 2>/dev/null && [[ $count -lt $timeout ]]; do
+            sleep 1
+            ((count++))
+        done
+        
+        if kill -0 "$pid" 2>/dev/null; then
+            print_warning "Process did not stop gracefully, sending SIGKILL..."
+            kill -KILL "$pid" 2>/dev/null || true
+            sleep 2
+        fi
+        
+        if ! kill -0 "$pid" 2>/dev/null; then
+            print_success "AxonHub stopped successfully (PID: $pid)"
+            rm -f "$PID_FILE"
+        else
+            print_error "Failed to stop AxonHub process"
+            return 1
+        fi
+    else
+        print_error "Failed to send signal to process $pid"
+        return 1
+    fi
+}
+
+stop_by_process_name() {
+    print_info "Stopping AxonHub by process name..."
+    
+    local pids
+    pids=$(pgrep -f "$PROCESS_NAME" 2>/dev/null || true)
+    
+    if [[ -z "$pids" ]]; then
+        print_warning "No AxonHub processes found"
+        return 1
+    fi
+    
+    print_info "Found AxonHub processes: $pids"
+    
+    for pid in $pids; do
+        print_info "Stopping process $pid..."
+        
+        if kill -TERM "$pid" 2>/dev/null; then
+            # Wait for graceful shutdown
+            local timeout=10
+            local count=0
+            
+            while kill -0 "$pid" 2>/dev/null && [[ $count -lt $timeout ]]; do
+                sleep 1
+                ((count++))
+            done
+            
+            if kill -0 "$pid" 2>/dev/null; then
+                print_warning "Process $pid did not stop gracefully, sending SIGKILL..."
+                kill -KILL "$pid" 2>/dev/null || true
+            fi
+        fi
+    done
+    
+    sleep 2
+    
+    # Check if any processes are still running
+    local remaining_pids
+    remaining_pids=$(pgrep -f "$PROCESS_NAME" 2>/dev/null || true)
+    
+    if [[ -z "$remaining_pids" ]]; then
+        print_success "All AxonHub processes stopped successfully"
+        rm -f "$PID_FILE"
+    else
+        print_error "Some AxonHub processes are still running: $remaining_pids"
+        return 1
+    fi
+}
+
+check_running_processes() {
+    local pids
+    pids=$(pgrep -f "$PROCESS_NAME" 2>/dev/null || true)
+    
+    if [[ -n "$pids" ]]; then
+        print_info "Running AxonHub processes:"
+        ps -p $pids -o pid,ppid,cmd --no-headers 2>/dev/null || true
+        return 0
+    else
+        return 1
+    fi
+}
+
+main() {
+    print_info "Stopping AxonHub..."
+    
+    local stopped=false
+    
+    # Try PID file first
+    if stop_by_pid; then
+        stopped=true
+    fi
+    
+    # If PID file method didn't work, try by process name
+    if [[ "$stopped" != true ]]; then
+        if stop_by_process_name; then
+            stopped=true
+        fi
+    fi
+    
+    # Final check
+    if [[ "$stopped" != true ]]; then
+        if check_running_processes; then
+            print_error "Failed to stop all AxonHub processes"
+            return 1
+        else
+            print_info "No AxonHub processes were running"
+        fi
+    fi
+    
+    # Clean up PID file
+    rm -f "$PID_FILE"
+    
+    print_success "AxonHub has been stopped"
+}
+
+# Handle script arguments
+case "${1:-}" in
+    --force)
+        print_info "Force stopping all AxonHub processes..."
+        if check_running_processes; then
+            pkill -KILL -f "$PROCESS_NAME" 2>/dev/null || true
+            sleep 2
+            if ! check_running_processes; then
+                print_success "All AxonHub processes force-stopped"
+                rm -f "$PID_FILE"
+            else
+                print_error "Failed to force-stop some processes"
+                exit 1
+            fi
+        else
+            print_info "No AxonHub processes found"
+        fi
+        ;;
+    --help|-h)
+        echo "Usage: $0 [--force]"
+        echo
+        echo "This script stops AxonHub directly (no systemd)."
+        echo "Options:"
+        echo "  --force     Force kill all AxonHub processes"
+        echo "  --help, -h  Show this help message"
+        exit 0
+        ;;
+    "")
+        main
+        ;;
+    *)
+        print_error "Unknown option: $1"
+        print_info "Use --help for usage information"
+        exit 1
+        ;;
+esac

docker-compose.yml

@@ -0,0 +1,172 @@
+# AxonHub Docker Compose Configuration
+#
+# CONFIGURATION OPTIONS:
+# 1. 环境变量 - 适用于敏感配置 (如数据库DSN、密码等)，优先级高于配置文件
+#    参考: https://github.com/looplj/axonhub/blob/main/docs/deployment/configuration.md#configuration-priority
+#
+# 2. 配置文件 - 适用于复杂配置 (如缓存、日志、监控等)
+#    创建 config.yml 文件并取消 volumes 配置的注释
+#    配置参考: https://github.com/looplj/axonhub/blob/main/docs/deployment/configuration.md
+#
+# 3. 简单部署 - 如果不需要复杂配置，可以注释掉 config 的 volumes 配置
+#    仅使用环境变量进行基本配置即可运行
+
+services:
+  # PostgreSQL 数据库
+  postgres:
+    image: postgres:16-alpine
+    container_name: axonhub-postgres
+    environment:
+      POSTGRES_DB: axonhub
+      POSTGRES_USER: axonhub
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-axonhub_password}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    networks:
+      - axonhub-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U axonhub"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # AxonHub 主服务
+  axonhub:
+    image: looplj/axonhub:latest
+    container_name: axonhub-app
+    environment:
+      # 数据库配置可以通过环境变量设置，优先级高于配置文件
+      AXONHUB_DB_DIALECT: postgres
+      AXONHUB_DB_DSN: postgres://axonhub:${DB_PASSWORD:-axonhub_password}@postgres:5432/axonhub?sslmode=disable
+    ports:
+      - "8090:8090"
+    volumes:
+      # 配置文件挂载 - 用于复杂配置，如缓存、日志、监控等
+      # 参考: https://github.com/looplj/axonhub/blob/main/docs/deployment/configuration.md
+      - ./config.yml:/app/config.yml:ro
+      # - axonhub_data:/data
+    networks:
+      - axonhub-network
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "wget",
+          "--no-verbose",
+          "--tries=1",
+          "--spider",
+          "http://localhost:8090/health",
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # SQLite 配置示例 (取消注释以使用 SQLite)
+  # 注意: 此服务与上面的 'axonhub' 服务冲突。请只启用其中一个。
+  # 先执行 
+  # mkdir data
+  # chmod 777 data
+  # axonhub-sqlite:
+  #   image: looplj/axonhub:latest
+  #   container_name: axonhub-sqlite-app
+  #   environment:
+  #     AXONHUB_DB_DIALECT: sqlite3
+  #     AXONHUB_DB_DSN: file:/data/axonhub.db?cache=shared&_fk=1
+  #   ports:
+  #     - "8090:8090"
+  #   volumes:
+  #     # 配置文件挂载 - 用于复杂配置
+  #     # 参考: https://github.com/looplj/axonhub/blob/main/docs/deployment/configuration.md
+  #     - ./config.yml:/app/config.yml:ro
+  #     - ./data:/data
+  #   restart: unless-stopped
+  #   healthcheck:
+  #     test:
+  #       [
+  #         "CMD",
+  #         "wget",
+  #         "--no-verbose",
+  #         "--tries=1",
+  #         "--spider",
+  #         "http://localhost:8090/health",
+  #       ]
+  #     interval: 30s
+  #     timeout: 10s
+  #     retries: 3
+  #     start_period: 40s
+
+  # MySQL 配置示例 (取消注释以使用 MySQL)
+  # 注意: 此服务与上面的 'axonhub' 服务冲突。请只启用其中一个。
+  # mysql:
+  #   image: mysql:8.0
+  #   container_name: axonhub-mysql
+  #   environment:
+  #     MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-axonhub_root_password}
+  #     MYSQL_DATABASE: axonhub
+  #     MYSQL_USER: axonhub
+  #     MYSQL_PASSWORD: ${MYSQL_PASSWORD:-axonhub_password}
+  #   volumes:
+  #     - mysql_data:/var/lib/mysql
+  #   ports:
+  #     - "3306:3306"
+  #   networks:
+  #     - axonhub-network
+  #   restart: unless-stopped
+  #   healthcheck:
+  #     test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD:-axonhub_root_password}"]
+  #     interval: 10s
+  #     timeout: 5s
+  #     retries: 5
+  #
+  # # AxonHub 主服务 (MySQL 版本)
+  # # 注意: 取消注释此服务时，请注释掉上面的 PostgreSQL 版本 axonhub 服务
+  # axonhub-mysql:
+  #   image: looplj/axonhub:latest
+  #   container_name: axonhub-mysql-app
+  #   environment:
+  #     AXONHUB_DB_DIALECT: mysql
+  #     # DSN 格式参考: ${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(mysql:3306)/${MYSQL_DATABASE}?charset=utf8mb4&parseTime=True&loc=Local
+  #     AXONHUB_DB_DSN: axonhub:${MYSQL_PASSWORD:-axonhub_password}@tcp(mysql:3306)/axonhub?charset=utf8mb4&parseTime=True&loc=Local
+  #   ports:
+  #     - "8090:8090"
+  #   volumes:
+  #     # 配置文件挂载 - 用于复杂配置
+  #     # 参考: https://github.com/looplj/axonhub/blob/main/docs/deployment/configuration.md
+  #     - ./config.yml:/app/config.yml:ro
+  #     # - axonhub_data:/data
+  #   networks:
+  #     - axonhub-network
+  #   depends_on:
+  #     mysql:
+  #       condition: service_healthy
+  #   restart: unless-stopped
+  #   healthcheck:
+  #     test:
+  #       [
+  #         "CMD",
+  #         "wget",
+  #         "--no-verbose",
+  #         "--tries=1",
+  #         "--spider",
+  #         "http://localhost:8090/health",
+  #       ]
+  #     interval: 30s
+  #     timeout: 10s
+  #     retries: 3
+  #     start_period: 40s
+
+volumes:
+  postgres_data:
+  mysql_data:
+
+networks:
+  axonhub-network:
+    driver: bridge

docs/en/api-reference/anthropic-api.md

@@ -0,0 +1,203 @@
+# Anthropic API Reference
+
+## Overview
+
+AxonHub supports the native Anthropic Messages API for applications that prefer Anthropic's specific features and response format. You can use the Anthropic SDK to access not only Claude models but also OpenAI, Gemini, and other supported models.
+
+## Key Benefits
+
+- **API Interoperability**: Use Anthropic Messages API to call OpenAI, Gemini, and other supported models
+- **Zero Code Changes**: Continue using your existing Anthropic client SDK without modification
+- **Automatic Translation**: AxonHub automatically converts between API formats when needed
+- **Provider Flexibility**: Access any supported AI provider using the Anthropic API format
+
+## Supported Endpoints
+
+**Endpoints:**
+- `POST /anthropic/v1/messages` - Text generation
+- `POST /v1/messages` - Text generation (alternative)
+- `GET /anthropic/v1/models` - List available models
+
+**Example Request:**
+```go
+import (
+    "github.com/anthropics/anthropic-sdk-go"
+    "github.com/anthropics/anthropic-sdk-go/option"
+)
+
+// Create Anthropic client with AxonHub configuration
+client := anthropic.NewClient(
+    option.WithAPIKey("your-axonhub-api-key"),
+    option.WithBaseURL("http://localhost:8090/anthropic"),
+    
+)
+
+// Call OpenAI model using Anthropic API format
+messages := []anthropic.MessageParam{
+    anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, GPT!")),
+}
+
+response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
+    Model:     anthropic.Model("gpt-4o"),
+    Messages:  messages,
+    MaxTokens: 1024,
+})
+if err != nil {
+    // Handle error appropriately
+    panic(err)
+}
+
+// Extract text content from response
+responseText := ""
+for _, block := range response.Content {
+    if textBlock := block.AsText(); textBlock != nil {
+        responseText += textBlock.Text
+    }
+}
+fmt.Println(responseText)
+```
+
+## API Translation Capabilities
+
+AxonHub automatically translates between API formats, enabling powerful scenarios:
+
+### Use Anthropic SDK with OpenAI Models
+```go
+// Anthropic SDK calling OpenAI model
+messages := []anthropic.MessageParam{
+    anthropic.NewUserMessage(anthropic.NewTextBlock("What is machine learning?")),
+}
+
+response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
+    Model:     anthropic.Model("gpt-4o"),  // OpenAI model
+    Messages:  messages,
+    MaxTokens: 1024,
+})
+
+// Access response
+for _, block := range response.Content {
+    if textBlock := block.AsText(); textBlock != nil {
+        fmt.Println(textBlock.Text)
+    }
+}
+// AxonHub automatically translates Anthropic format → OpenAI format
+```
+
+### Use Anthropic SDK with Gemini Models
+```go
+// Anthropic SDK calling Gemini model
+messages := []anthropic.MessageParam{
+    anthropic.NewUserMessage(anthropic.NewTextBlock("Explain quantum computing")),
+}
+
+response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
+    Model:     anthropic.Model("gemini-2.5"),  // Gemini model
+    Messages:  messages,
+    MaxTokens: 1024,
+})
+
+// Access response
+for _, block := range response.Content {
+    if textBlock := block.AsText(); textBlock != nil {
+        fmt.Println(textBlock.Text)
+    }
+}
+// AxonHub automatically translates Anthropic format → Gemini format
+```
+
+## Authentication
+
+The Anthropic API format uses the following authentication:
+
+- **Header**: `X-API-Key: <your-api-key>`
+
+The API keys are managed through AxonHub's API Key management system and provide the same permissions regardless of which API format you use.
+
+## Streaming Support
+
+Anthropic API format supports streaming responses:
+
+```go
+// Anthropic SDK streaming
+messages := []anthropic.MessageParam{
+    anthropic.NewUserMessage(anthropic.NewTextBlock("Count to five")),
+}
+
+stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
+    Model:     anthropic.Model("gpt-4o"),
+    Messages:  messages,
+    MaxTokens: 1024,
+})
+
+// Collect streamed content
+var content string
+for stream.Next() {
+    event := stream.Current()
+    switch event := event.(type) {
+    case anthropic.ContentBlockDeltaEvent:
+        if event.Type == "content_block_delta" {
+            content += event.Delta.Text
+            fmt.Print(event.Delta.Text) // Print as it streams
+        }
+    }
+}
+
+if err := stream.Err(); err != nil {
+    panic(err)
+}
+
+fmt.Println("\nComplete response:", content)
+```
+
+## Error Handling
+
+Anthropic format error responses:
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "invalid_request_error",
+    "message": "Invalid API key"
+  }
+}
+```
+
+## Tool Support
+
+AxonHub supports **function tools** (custom function calling) through the Anthropic API format. However, provider-specific tools are **not supported**:
+
+| Tool Type | Support Status | Notes |
+| --------- | -------------- | ----- |
+| **Function Tools** | �� Supported | Custom function definitions work across all providers |
+| **Web Search** | ❌ Not Supported | Provider-specific (OpenAI, Anthropic, etc.) |
+| **Code Interpreter** | ❌ Not Supported | Provider-specific (OpenAI, Anthropic, etc.) |
+| **File Search** | ❌ Not Supported | Provider-specific |
+| **Computer Use** | ❌ Not Supported | Anthropic-specific |
+
+> **Note**: Only generic function tools that can be translated across providers are supported. Provider-specific tools like web search, code interpreter, and computer use require direct access to the provider's infrastructure and cannot be proxied through AxonHub.
+
+## Best Practices
+
+1. **Use Tracing Headers**: Include `AH-Trace-Id` and `AH-Thread-Id` headers for better observability
+2. **Model Selection**: Specify the target model explicitly in your requests
+3. **Error Handling**: Implement proper error handling for API responses
+4. **Streaming**: Use streaming for better user experience with long responses
+5. **Use Function Tools**: For tool calling, use generic function tools instead of provider-specific tools
+
+## Migration Guide
+
+### From Anthropic to AxonHub
+```go
+// Before: Direct Anthropic
+client := anthropic.NewClient(
+    option.WithAPIKey("anthropic-key"),
+)
+
+// After: AxonHub with Anthropic API
+client := anthropic.NewClient(
+    option.WithAPIKey("axonhub-api-key"),
+    option.WithBaseURL("http://localhost:8090/anthropic"),
+)
+// Your existing code continues to work!
+```

docs/en/api-reference/embedding-api.md

@@ -0,0 +1,176 @@
+# Embedding API Reference
+
+## Overview
+
+AxonHub provides comprehensive support for text and multimodal embedding generation through OpenAI-compatible and Jina AI-specific APIs.
+
+## Key Benefits
+
+- **OpenAI Compatibility**: Use existing OpenAI SDKs without modification
+- **Jina AI Support**: Native Jina embedding format support for specialized use cases
+- **Multiple Input Types**: Support for single text, text arrays, token arrays, and multiple token arrays
+- **Flexible Output Formats**: Choose between float arrays or base64-encoded embeddings
+
+## Supported Endpoints
+
+**Endpoints:**
+- `POST /v1/embeddings` - OpenAI-compatible embedding API
+- `POST /jina/v1/embeddings` - Jina AI-specific embedding API
+
+## Request Format
+
+```json
+{
+  "input": "The text to embed",
+  "model": "text-embedding-3-small",
+  "encoding_format": "float",
+  "dimensions": 1536,
+  "user": "user-id"
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `input` | string \| string[] \| number[] \| number[][] | ✅ | The text(s) to embed. Can be a single string, array of strings, token array, or multiple token arrays. |
+| `model` | string | ✅ | The model to use for embedding generation. |
+| `encoding_format` | string | ❌ | Format to return embeddings in. Either `float` or `base64`. Default: `float`. |
+| `dimensions` | integer | ❌ | Number of dimensions for the output embeddings. |
+| `user` | string | ❌ | Unique identifier for the end-user. |
+
+**Jina-Specific Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task` | string | ❌ | Task type for Jina embeddings. Options: `text-matching`, `retrieval.query`, `retrieval.passage`, `separation`, `classification`, `none`. |
+
+## Response Format
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "embedding": [0.123, 0.456, ...],
+      "index": 0
+    }
+  ],
+  "model": "text-embedding-3-small",
+  "usage": {
+    "prompt_tokens": 4,
+    "total_tokens": 4
+  }
+}
+```
+
+## Examples
+
+### OpenAI SDK (Python)
+
+```python
+import openai
+
+client = openai.OpenAI(
+    api_key="your-axonhub-api-key",
+    base_url="http://localhost:8090/v1"
+)
+
+response = client.embeddings.create(
+    input="Hello, world!",
+    model="text-embedding-3-small"
+)
+
+print(response.data[0].embedding[:5])  # First 5 dimensions
+```
+
+### OpenAI SDK (Go)
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/openai/openai-go"
+    "github.com/openai/openai-go/option"
+)
+
+func main() {
+    client := openai.NewClient(
+        option.WithAPIKey("your-axonhub-api-key"),
+        option.WithBaseURL("http://localhost:8090/v1"),
+    )
+
+    embedding, err := client.Embeddings.New(context.TODO(), openai.EmbeddingNewParams{
+        Input: openai.Union[string](openai.String("Hello, world!")),
+        Model: openai.String("text-embedding-3-small"),
+        option.WithHeader("AH-Trace-Id", "trace-example-123"),
+        option.WithHeader("AH-Thread-Id", "thread-example-abc"),
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Embedding dimensions: %d\n", len(embedding.Data[0].Embedding))
+    fmt.Printf("First 5 values: %v\n", embedding.Data[0].Embedding[:5])
+}
+```
+
+### Multiple Texts
+
+```python
+response = client.embeddings.create(
+    input=["Hello, world!", "How are you?"],
+    model="text-embedding-3-small"
+)
+
+for i, data in enumerate(response.data):
+    print(f"Text {i}: {data.embedding[:3]}...")
+```
+
+### Jina-Specific Task
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8090/jina/v1/embeddings",
+    headers={
+        "Authorization": "Bearer your-axonhub-api-key",
+        "Content-Type": "application/json"
+    },
+    json={
+        "input": "What is machine learning?",
+        "model": "jina-embeddings-v2-base-en",
+        "task": "retrieval.query"
+    }
+)
+
+result = response.json()
+print(result["data"][0]["embedding"][:5])
+```
+
+## Authentication
+
+The Embedding API uses Bearer token authentication:
+
+- **Header**: `Authorization: Bearer <your-api-key>`
+
+The API keys are managed through AxonHub's API Key management system.
+
+## Best Practices
+
+1. **Use Tracing Headers**: Include `AH-Trace-Id` and `AH-Thread-Id` headers for better observability
+2. **Batch Requests**: When embedding multiple texts, send them in a single request for better performance
+3. **Choose Appropriate Dimensions**: Use the `dimensions` parameter to reduce embedding size if full dimensionality isn't needed
+4. **Select Proper Encoding**: Use `base64` encoding if you need to transmit embeddings over the network to reduce payload size
+5. **Jina Task Types**: When using Jina embeddings, select the appropriate `task` type for your use case to optimize retrieval quality
+
+## Related Resources
+
+- [OpenAI API](openai-api.md)
+- [Rerank API](rerank-api.md)

docs/en/api-reference/gemini-api.md

@@ -0,0 +1,214 @@
+# Gemini API Reference
+
+## Overview
+
+AxonHub provides native support for the Gemini API, enabling access to Gemini's powerful multi-modal capabilities. You can use the Gemini SDK to access not only Gemini models but also OpenAI, Anthropic, and other supported models.
+
+## Key Benefits
+
+- **API Interoperability**: Use Gemini API to call OpenAI, Anthropic, and other supported models
+- **Zero Code Changes**: Continue using your existing Gemini client SDK without modification
+- **Automatic Translation**: AxonHub automatically converts between API formats when needed
+- **Multi-modal Support**: Access text and image capabilities through the Gemini API format
+
+## Supported Endpoints
+
+**Endpoints:**
+- `POST /gemini/v1beta/models/{model}:generateContent` - Text and multi-modal content generation
+- `POST /v1beta/models/{model}:generateContent` - Text and multi-modal content generation (alternative)
+- `GET /gemini/v1beta/models` - List available models
+- `GET /v1beta/models` - List available models (alternative)
+
+**Example Request:**
+```go
+import (
+    "context"
+    "google.golang.org/genai"
+)
+
+// Create Gemini client with AxonHub configuration
+ctx := context.Background()
+client, err := genai.NewClient(ctx, &genai.ClientConfig{
+    APIKey:  "your-axonhub-api-key",
+    Backend: genai.Backend(genai.APIBackendUnspecified), // Use default backend
+    HTTPOptions: genai.HTTPOptions{
+			BaseURL: "http://localhost:8090/gemini",
+	},
+})
+if err != nil {
+    // Handle error appropriately
+    panic(err)
+}
+
+// Call OpenAI model using Gemini API format
+modelName := "gpt-4o"  // OpenAI model accessed via Gemini API format
+content := &genai.Content{
+    Parts: []*genai.Part{
+        {Text: genai.Ptr("Hello, GPT!")},
+    },
+}
+
+// Optional: Configure generation parameters
+config := &genai.GenerateContentConfig{
+    Temperature: genai.Ptr(float32(0.7)),
+    MaxOutputTokens: genai.Ptr(int32(1024)),
+}
+
+response, err := client.Models.GenerateContent(ctx, modelName, []*genai.Content{content}, config)
+if err != nil {
+    // Handle error appropriately
+    panic(err)
+}
+
+// Extract text from response
+if len(response.Candidates) > 0 &&
+   len(response.Candidates[0].Content.Parts) > 0 {
+    responseText := response.Candidates[0].Content.Parts[0].Text
+    fmt.Println(*responseText)
+}
+```
+
+**Example: Multi-turn Conversation**
+```go
+// Create a chat session with conversation history
+modelName := "claude-3-5-sonnet"
+config := &genai.GenerateContentConfig{
+    Temperature: genai.Ptr(float32(0.5)),
+}
+
+chat, err := client.Chats.Create(ctx, modelName, config, nil)
+if err != nil {
+    panic(err)
+}
+
+// First message
+response1, err := chat.SendMessage(ctx, genai.Part{Text: genai.Ptr("My name is Alice")})
+if err != nil {
+    panic(err)
+}
+
+// Follow-up message (model remembers context)
+response2, err := chat.SendMessage(ctx, genai.Part{Text: genai.Ptr("What is my name?")})
+if err != nil {
+    panic(err)
+}
+
+// Extract response
+if len(response2.Candidates) > 0 {
+    text := response2.Candidates[0].Content.Parts[0].Text
+    fmt.Println(*text)  // Should contain "Alice"
+}
+```
+
+## API Translation Capabilities
+
+AxonHub automatically translates between API formats, enabling powerful scenarios:
+
+### Use Gemini SDK with OpenAI Models
+```go
+// Gemini SDK calling OpenAI model
+content := &genai.Content{
+    Parts: []*genai.Part{
+        {Text: genai.Ptr("Explain neural networks")},
+    },
+}
+
+response, err := client.Models.GenerateContent(
+    ctx,
+    "gpt-4o",  // OpenAI model
+    []*genai.Content{content},
+    nil,
+)
+
+// Access response
+if len(response.Candidates) > 0 &&
+   len(response.Candidates[0].Content.Parts) > 0 {
+    text := response.Candidates[0].Content.Parts[0].Text
+    fmt.Println(*text)
+}
+// AxonHub automatically translates Gemini format → OpenAI format
+```
+
+### Use Gemini SDK with Anthropic Models
+```go
+// Gemini SDK calling Anthropic model
+content := &genai.Content{
+    Parts: []*genai.Part{
+        {Text: genai.Ptr("What is artificial intelligence?")},
+    },
+}
+
+response, err := client.Models.GenerateContent(
+    ctx,
+    "claude-3-5-sonnet",  // Anthropic model
+    []*genai.Content{content},
+    nil,
+)
+
+// Access response
+if len(response.Candidates) > 0 &&
+   len(response.Candidates[0].Content.Parts) > 0 {
+    text := response.Candidates[0].Content.Parts[0].Text
+    fmt.Println(*text)
+}
+// AxonHub automatically translates Gemini format → Anthropic format
+```
+
+## Authentication
+
+The Gemini API format uses the following authentication:
+
+- **Header**: `X-Goog-API-Key: <your-api-key>`
+
+The API keys are managed through AxonHub's API Key management system and provide the same permissions regardless of which API format you use.
+
+## Streaming Support
+
+Gemini API format supports streaming responses for real-time content generation.
+
+## Error Handling
+
+Gemini format error responses follow the standard Gemini API error format.
+
+## Tool Support
+
+AxonHub supports **function tools** (custom function calling) through the Gemini API format. However, provider-specific tools are **not supported**:
+
+| Tool Type | Support Status | Notes |
+| --------- | -------------- | ----- |
+| **Function Tools** | ✅ Supported | Custom function definitions work across all providers |
+| **Web Search** | ❌ Not Supported | Provider-specific |
+| **Code Interpreter** | ❌ Not Supported | Provider-specific |
+| **File Search** | ❌ Not Supported | Provider-specific |
+| **Computer Use** | ❌ Not Supported | Anthropic-specific |
+
+> **Note**: Only generic function tools that can be translated across providers are supported. Provider-specific tools require direct access to the provider's infrastructure and cannot be proxied through AxonHub.
+
+## Best Practices
+
+1. **Use Tracing Headers**: Include `AH-Trace-Id` and `AH-Thread-Id` headers for better observability
+2. **Model Selection**: Specify the target model explicitly in your requests
+3. **Error Handling**: Implement proper error handling for API responses
+4. **Streaming**: Use streaming for better user experience with long responses
+5. **Multi-modal Content**: Leverage Gemini API's multi-modal capabilities when working with images
+
+## Migration Guide
+
+### From Gemini to AxonHub
+```go
+// Before: Direct Gemini
+ctx := context.Background()
+client, err := genai.NewClient(ctx, &genai.ClientConfig{
+    APIKey: "gemini-api-key",
+})
+
+// After: AxonHub with Gemini API
+ctx := context.Background()
+client, err := genai.NewClient(ctx, &genai.ClientConfig{
+    APIKey: "your-axonhub-api-key",
+    HTTPOptions: genai.HTTPOptions{
+        BaseURL: "http://localhost:8090/gemini",
+    },
+})
+// Your existing code continues to work!
+```