Deployment Guide

Single-instance release build:

cargo build -p gproxy --release

If you changed the embedded console frontend, build it before packaging or running the binary:

cd frontend/console
pnpm install
pnpm build

The output binary is located at target/release/gproxy.

The current binary includes an embedded browser console mounted at /console.

• Console URL: http://127.0.0.1:8787/console
• Browser login: POST /login
• Browser auth header: Authorization: Bearer <session_token>

Typical local workflow:

cd frontend/console
pnpm install
pnpm build

cargo run -p gproxy

Then open /console in a browser and log in with a current v1 username and password.

The full set of startup parameters and their corresponding environment variables are defined in apps/gproxy/src/main.rs:

Additional Notes:

• CLI arguments and environment variables are both parsed by clap; explicit CLI values take priority over defaults.
• If the database already contains global_settings and GPROXY_DSN / GPROXY_DATA_DIR were not passed explicitly at startup, the process will reconnect to the database using the persisted configuration.

The TOML file pointed to by GPROXY_CONFIG is only used during initialization when the database does not already contain data. The corresponding structure is defined in crates/gproxy-api/src/admin/config_toml.rs.

[global]
host = "0.0.0.0"
port = 8787
proxy = "http://127.0.0.1:7890"
spoof_emulation = "chrome_136"
update_source = "github"
enable_usage = true
enable_upstream_log = false
enable_upstream_log_body = false
enable_downstream_log = false
enable_downstream_log_body = false
dsn = "sqlite://./data/gproxy.db?mode=rwc"
data_dir = "./data"

[[providers]]
name = "openai-main"
channel = "openai"
settings = { base_url = "https://api.openai.com/v1" }
credentials = [
  { api_key = "sk-provider-1" }
]

[[models]]
provider_name = "openai-main"
model_id = "gpt-4.1-mini"
display_name = "GPT-4.1 mini"
enabled = true
price_each_call = 0.0

[[model_aliases]]
alias = "chat-default"
provider_name = "openai-main"
model_id = "gpt-4.1-mini"
enabled = true

[[users]]
name = "alice"
password = "plain-text-or-argon2-phc"
enabled = true

[[users.keys]]
api_key = "sk-user-1"
label = "default"
enabled = true

[[permissions]]
user_name = "alice"
provider_name = "openai-main"
model_pattern = "gpt-*"

[[file_permissions]]
user_name = "alice"
provider_name = "openai-main"

[[rate_limits]]
user_name = "alice"
model_pattern = "gpt-*"
rpm = 60
rpd = 10000
total_tokens = 200000

[[quotas]]
user_name = "alice"
quota = 100.0
cost_used = 0.0

Field Descriptions:

• [global] covers global listen address, logging, update source, DSN, and data directory configuration.
• [[providers]] defines a provider; settings and credentials are both JSON values read via serde_json::Value.
• [[models]] / [[model_aliases]] define forwardable models and their aliases.
• Admin access is represented by [[users]] entries with is_admin = true and at least one enabled [[users.keys]] entry. If the seed config does not define such an admin, startup can bootstrap one from GPROXY_ADMIN_USER, GPROXY_ADMIN_PASSWORD, and GPROXY_ADMIN_API_KEY.
• The password field under [[users]] can be either plaintext or a direct Argon2 PHC hash.
• [[users.keys]] is a nested array table representing the user's API key list.
• [[permissions]], [[file_permissions]], [[rate_limits]], and [[quotas]] correspond to model permissions, file permissions, rate limiting, and cost quotas respectively.

gproxy-storage compiles in three database backends via SeaORM / SQLx:

Common DSN examples:

sqlite://./data/gproxy.db?mode=rwc
postgres://gproxy:secret@127.0.0.1:5432/gproxy
mysql://gproxy:secret@127.0.0.1:3306/gproxy

After establishing the connection, SeaOrmStorage::connect() will:

1. Optionally load the database encryptor corresponding to DATABASE_SECRET_KEY.
2. Apply per-database connection tuning parameters.
3. Connect to the database and run sync() to synchronize the schema.

Graceful shutdown behavior is jointly implemented by apps/gproxy/src/main.rs and apps/gproxy/src/workers/mod.rs:

1. The process listens for Ctrl+C; on Unix it also listens for SIGTERM.
2. Once shutdown is triggered, the Axum server enters the with_graceful_shutdown flow and stops accepting new requests.
3. The main thread then calls worker_set.shutdown(), broadcasting the shutdown signal to all workers.
4. WorkerSet waits up to 5 seconds for workers to drain.
5. UsageSink closes its receiver, drains remaining usage messages, and performs a final batch write.
6. HealthBroadcaster flushes any health states still in its debounce window to the database.
7. QuotaReconciler and RateLimitGC exit their next loop iteration upon receiving the signal.
8. If any workers have not finished within 5 seconds, the process logs a warning but does not block indefinitely.