Ershu API

简体中文

Ershu API is the HTTP backend for the Ershu web application and other HTTP clients. It is intended for people who operate Ershu and contributors working on its web boundary. The service handles account setup and login, project access, analysis run control, documents, search, chat, administration, browser sessions, and streamed responses.

Repository analysis runs in Ershu Worker. This service queues and controls that work, then serves the stored results. It does not import Worker or MCP code.

What the API owns

The API can rebuild search entries from data already stored in Ershu and expose maintenance operations. Ershu Worker owns repository analysis and the generation of project documents, code facts, and knowledge relationships.

Where it fits

Frontend and HTTP clients
           |
           v
       Ershu API --------------> PostgreSQL
           |                     Redis
           |                     Milvus
           |
           +---- queued runs ---> Ershu Worker

Ershu MCP uses shared Core services and storage. MCP traffic does not pass
through Ershu API.

Each component is released independently. The deployment repository selects the exact set of component versions used together.

Install and commands

Install the API as part of a tested component set through the ershu installer package:

pip install "ershu[api]"

Projects that depend on the API package directly can pin the component with UV:

uv add "ershu-api==1.0.0.post20260812"

Requirements

Development requires:

• Python 3.14 or newer
• UV
• A compatible ershu-core release

Running the service also requires PostgreSQL, Redis, and Milvus. PostgreSQL stores application state, Redis backs login rate limiting and the poller lease, and Milvus holds vectors used by semantic search.

Run from source

Install the locked runtime dependencies:

uv sync --locked

Copy .env.example to .env. Generate three independent values for SECRET_KEY, ENCRYPTION_KEY, and MCP_KEY_PEPPER:

uv run python -c "import secrets; print(*(secrets.token_urlsafe(48) for _ in range(3)), sep='\n')"

Use one output line for each setting. Do not reuse a value. The example placeholders are rejected at startup, and .env must not be committed.

Start PostgreSQL, Redis, and Milvus, then apply the database migrations:

uv run ershu-db upgrade head

Start the API:

uv run ershu-api

The development server listens on 127.0.0.1:8000 by default and reloads when source files change. OpenAPI pages are available only in development:

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/redoc

Health checks

The root and versioned health endpoints report whether the HTTP process can respond:

curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/api/v1/health

Both return {"status":"ok"}. Check PostgreSQL and Milvus separately:

curl -fsS http://127.0.0.1:8000/api/v1/health/dependencies

The dependency response is degraded when either check fails. It does not test Redis.

Configuration

The service reads .env from its working directory. .env.example lists the supported deployment settings.

LLM, embedding, and reranker channels are managed through the administration endpoints. Their API keys are encrypted before storage and do not belong in .env.

Some non-secret operational settings can be overridden in the database through the system settings endpoints. Environment values remain the startup defaults.

OPAQUE server setup

Development can leave OPAQUE_SERVER_SETUP empty. On first startup, the API creates an OPAQUE server setup and stores it encrypted in PostgreSQL.

Production requires an explicit, stable value. Generate it once:

uv run python -c "import base64, opaque_ke_py; print(base64.urlsafe_b64encode(opaque_ke_py.server_setup().to_bytes()).decode('ascii').rstrip('='))"

Store the output in the deployment secret store. Changing this value prevents existing OPAQUE password records from being used.

Repository polling

Repositories with polling enabled need a separate long-running process:

uv run ershu-api-poller

Cron expressions use UTC. Poller instances coordinate through a renewable Redis lease, so more than one instance can run without processing the same schedule at once. A single cycle can be run manually:

uv run ershu-api-poller --once

The API and poller must use the same PostgreSQL database, Redis instance, and encryption settings. The poller detects revisions and queues refresh runs. A running Worker is still required to process them.

Repository webhooks

Repository webhooks use HMAC-SHA256 over this byte sequence:

timestamp + NUL + nonce + NUL + raw request body

Send the lowercase hexadecimal digest in X-Ershu-Webhook-Signature, the Unix timestamp in X-Ershu-Webhook-Timestamp, and a unique nonce in X-Ershu-Webhook-Nonce. The timestamp must be within five minutes of the server clock. The exact raw body used to compute the signature must be sent unchanged.

The webhook endpoint is under /api/v1/webhooks/repositories/{repository_id}. A valid webhook queues work; it does not run repository analysis inside the request.

Production checklist

• Set ENVIRONMENT=production and SESSION_COOKIE_SECURE=true.
• Keep SECRET_KEY, ENCRYPTION_KEY, MCP_KEY_PEPPER, and OPAQUE_SERVER_SETUP in a secret store. Use different, stable values.
• Terminate TLS at the service or a trusted reverse proxy. Production API requests over plain HTTP are rejected.
• Limit FORWARDED_ALLOW_IPS to the actual proxy addresses and pass the external host and scheme correctly.
• Add only the real frontend origins to CORS_ORIGINS.
• Keep ALLOW_DEV_OPEN_LOCAL_REPOSITORY_PATHS=false.
• Route /api/v1/ to this service. Route /mcp/ to Ershu MCP, not to Ershu API.

The API rejects weak or reused service secrets at startup. The development OpenAPI pages are disabled in production.

Development

Install the development dependencies:

uv sync --extra dev --locked

Run the repository checks:

uv run --extra dev pytest -q
uv run --extra dev ruff check src tests
uv run --extra dev ruff format --check src tests
uv build --wheel --out-dir dist

The test suite uses temporary SQLite databases and replaces external services, so it does not require live PostgreSQL, Redis, or Milvus instances.

Repository layout

Changes to HTTP requests, responses, errors, cookies, CSRF behavior, or stream events can affect the frontend and other clients. Changes to shared data, permissions, or query behavior belong in ershu-core; analysis and generation changes belong in ershu-worker; MCP tool changes belong in ershu-mcp.

License

Ershu API is licensed under the Apache License 2.0.