為 AI DevOps 打造零幻覺反向代理：構建 Cognee 的 Caddyfile 連接器

Autonomous AI DevOps and site reliability engineering (SRE) agents—such as Claude Code, Devin, Cursor, and GitHub Copilot—are increasingly being used to diagnose routing issues, configure SSL certificates, and manage reverse proxies for microservices.

But there's a catch: an AI agent can generate a plausible configuration without knowing how your infrastructure is actually configured.

That gap can lead to problems such as:

• Port confusion: Routing requests to localhost:8000 when the service actually listens on port 8080.
• Incorrect path matching: Confusing Caddy's named matchers, such as @api, with directives such as handle_path, or overlooking when a path prefix needs to be stripped.
• Header-handling mistakes: Misunderstanding how request headers such as X-Forwarded-For and X-Real-IP are configured or propagated.
• TLS misconfiguration: Suggesting invalid directives or overlooking existing HTTPS and certificate settings.

Why does this happen? An LLM may rely on general examples instead of the application's actual routing rules, upstream addresses, and server configuration.

Caddy is a modern web server known for automatic HTTPS and its human-readable, declarative Caddyfile configuration format. A Caddyfile describes site addresses, handlers, matchers, reverse proxies, and other aspects of server behavior.

As part of Mergetober, I built the Caddy Web Server Data-Source Connector for Cognee, named cognee-community-connector-caddy.

The goal is to make Caddy configuration available through Cognee's knowledge and retrieval workflow, helping AI agents access relevant routing context before recommending infrastructure changes.

In this article, we'll explore why Caddyfile context matters, look at the connector's intended architecture, and walk through an example ingestion workflow.

1. Why Caddyfile Routing Context Matters

In modern cloud and edge infrastructure, Caddy often acts as an entry point for web traffic. A production Caddyfile may define several important pieces of infrastructure context:

• Site addresses and ports: Hosts and listening addresses such as example.com, api.example.com, :80, and :443.
• Path matchers and handlers: Routing rules such as @api path /api/* and handle_path /docs/*.
• Reverse proxy upstreams: Backend addresses and proxy targets, such as reverse_proxy 127.0.0.1:8080.
• Headers and URL rewrites: Request and response header behavior, along with path transformations.
• TLS configuration: Automatic HTTPS behavior and custom certificate settings.

Imagine asking an AI DevOps agent to:

• "Add a route for the analytics service."
• "Troubleshoot why the docs endpoint returns a 404."
• "Find out which backend handles requests to /api/*."
• "Check whether the existing reverse proxy uses the correct port."

Before suggesting changes, the agent needs to understand the existing configuration.

Making the Caddyfile searchable gives the agent a way to retrieve relevant routing definitions rather than relying entirely on generic configuration patterns.

2. Introducing Cognee: Memory for Web Routing

Cognee is an open-source framework for building AI memory systems using structured knowledge and retrieval.

The Caddy connector aims to make routing configuration easier for developers and AI agents to discover.

Its intended use cases include:

• Site and proxy discovery: Finding site blocks, matchers, and reverse proxy definitions.
• Routing relationships: Representing relationships between hosts, path matchers, and upstream backends where supported by the connector and ingestion pipeline.
• Semantic retrieval: Asking natural-language questions such as, "Which backend handles requests to /auth/?"
• Context-informed configuration: Providing relevant configuration details before an agent proposes routing or reverse proxy changes.

For example, an agent could ask:

What backend port handles /v1/* requests on api.company.com?

If the corresponding configuration has been ingested and the retrieval pipeline returns the relevant information, the agent can use that context to inform its answer.

The important distinction is that retrieval provides evidence for an agent to reason from. It doesn't automatically guarantee that every answer is correct or that a proposed configuration is safe to deploy.

3. Architectural Overview: The Caddy Connector

The intended workflow connects a Caddyfile to Cognee's ingestion and retrieval pipeline, making configuration information available to an AI DevOps agent.

┌───────────────────────────────┐
│       Caddyfile               │
│  Sites, Matchers, Proxies     │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  Caddy Web Server Connector   │
│  cognee-community-connector-  │
│  caddy                        │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  Parse Relevant Configuration │
│  Sites, Proxies, Matchers,    │
│  and Directives               │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│      Cognee Ingestion         │
│  Knowledge Processing         │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  Structured Knowledge and    │
│  Retrieval                    │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│       AI DevOps Agent         │
│  Context-Informed Suggestions │
└───────────────────────────────┘

The diagram illustrates the intended architecture, not a claim that every stage has been independently validated in production.

3.1. Stable Entity Identifiers

A connector can assign deterministic identifiers to site blocks and other configuration entities.

For example:

caddy:site:{primary_address_slug}

Possible identifiers include:

caddy:site:example_com
caddy:site:api_company_com

Consistent identifiers can help identify the same logical entity across repeated imports. Whether this prevents duplicate knowledge nodes depends on how the connector and Cognee ingestion pipeline handle entity identity and deduplication.

3.2. Keeping Routing Knowledge Synchronized

Web server configurations change as services are deployed, decommissioned, and reconfigured. A useful connector should account for those changes so that retrieved knowledge doesn't continue to describe routes that no longer exist.

A replacement strategy, such as write_disposition="replace", may be relevant to this workflow. However, replacing imported data does not by itself prove that all obsolete knowledge entities and relationships will be deleted. That behavior depends on the connector's implementation and Cognee's cleanup semantics.

For reliable synchronization, test the complete lifecycle:

1. Ingest a Caddyfile containing a site and upstream.
2. Remove or change that site or upstream.
3. Re-ingest the modified configuration.
4. Search for the old route and verify that obsolete information is no longer returned.

This is especially important when AI agents use retrieved configuration to recommend changes to production infrastructure.

3.3. Agent-Friendly Configuration Representations

A Caddy site can be summarized in a compact, readable representation:

Site: api.company.com
Matchers:
  - name: "@api"
    path: "/v1/*"
Handlers:
  - type: reverse_proxy
    upstream: "127.0.0.1:8080"
Headers:
  - Strict-Transport-Security: "max-age=31536000"
TLS: Automatic HTTPS

This is an illustrative summary, not native Caddyfile syntax. The exact representation produced by the connector depends on its parser and data model.

It highlights the information an agent may need when reasoning about routing:

• Site address
• Path matcher
• Reverse proxy target
• Relevant headers
• TLS behavior

The more accurately these details are represented and retrieved, the better the agent can ground its recommendations in the application's existing configuration.

4. Step-by-Step: Ingesting a Caddyfile into Cognee

Let's look at an example workflow for loading routing configuration into Cognee and querying it.

Note: The commands and code below illustrate the intended integration. Confirm the connector's published package name, import path, function signature, and supported Cognee API parameters against the implementation in PR #496 before running the example.

Step 1: Install the Dependencies

Install Cognee and the connector:

pip install cognee cognee-community-connector-caddy

If the connector has not been published to the package index, install it using the installation instructions provided by the pull request instead.

Step 2: Prepare Your Directory

Create a project directory containing your Caddyfile and Python script:

routing-project/
├── Caddyfile
└── index_routes.py

For this example, the Caddyfile defines separate routes for the API and analytics services.

api.company.com {
    @api path /v1/*
    reverse_proxy @api 127.0.0.1:8080

    @analytics path /analytics/*
    reverse_proxy @analytics 127.0.0.1:9090
}

Here:

• Requests matching /v1/* are sent to 127.0.0.1:8080.
• Requests matching /analytics/* are sent to 127.0.0.1:9090.

The path matcher selects matching requests. Unlike handle_path, it does not itself strip the matched path prefix before proxying.

Step 3: Ingest and Search the Routing Configuration

Create index_routes.py:

import asyncio

import cognee
from cognee_community_connector_caddy import caddy_source


async def main():
    # 1. Load the Caddyfile through the connector.
    print("Loading Caddyfile into Cognee...")

    source = caddy_source(
        caddyfile_path="./Caddyfile"
    )

    # 2. Ingest the configuration.
    await cognee.remember(
        source,
        dataset_name="web_routing",
        max_rows_per_table=0,
    )

    # 3. Process the ingested information.
    print("Building routing knowledge...")

    await cognee.cognify(
        dataset_name="web_routing",
    )

    # 4. Search for routing information.
    print("Searching routing configuration...")

    results = await cognee.search(
        "What backend port handles /v1/* requests on api.company.com?",
        dataset_name="web_routing",
    )

    for result in results:
        print(f"\n{result}")


if __name__ == "__main__":
    asyncio.run(main())

The example demonstrates four conceptual stages:

1. Load: Read the Caddyfile using the connector.
2. Ingest: Pass the source to Cognee.
3. Process: Build the knowledge representation.
4. Retrieve: Ask a natural-language question about a route.

The caddy_source import, caddyfile_path argument, and max_rows_per_table parameter are example API usage and should be checked against the actual connector and Cognee versions. You may also need to configure Cognee's storage and language-model settings before ingestion.

Step 4: Inspect the Results

For the sample configuration, the expected answer to the query is that requests matching /v1/* on api.company.com are proxied to 127.0.0.1:8080.

Treat this as the expected result of the example, not a verified execution result.

Before relying on the connector in a real environment, test several cases:

• A route that exists.
• A route that does not exist.
• A changed upstream port.
• A removed matcher or site.
• Multiple site blocks with different upstreams.

These tests help establish whether the connector captures the relevant configuration correctly and whether retrieval reflects subsequent changes.

5. From Retrieved Context to Better-Informed Proxy Changes

Suppose an AI agent retrieves the existing routing configuration and discovers that the API and analytics services use different backend ports.

It can use that context when proposing a configuration such as:

api.company.com {
    @api path /v1/*
    reverse_proxy @api 127.0.0.1:8080

    @analytics path /analytics/*
    reverse_proxy @analytics 127.0.0.1:9090
}

Instead of guessing the upstream targets from generic examples, the agent can reference the configuration available through the retrieval workflow.

That distinction matters in DevOps: a plausible configuration isn't necessarily the right configuration for a particular application.

The connector is intended to support a more grounded workflow:

1. Retrieve the existing configuration.
2. Identify the relevant site, matcher, and upstream.
3. Propose a change based on the retrieved information.
4. Validate the proposed configuration.
5. Test the behavior before deploying it.

Retrieval alone doesn't eliminate hallucinations or guarantee safe changes. Production use should still include Caddy configuration validation, appropriate tests, and human review for consequential changes.

6. Open-Source Pull Request and References

This connector was developed as part of the Cognee Mergetober community contribution series.

• Connector pull request: Cognee Community PR #496
• Related issue: Cognee issue #6318
• Cognee repository: github.com/topoteretes/cognee
• Caddy documentation: caddyserver.com/docs

Check the pull request for the connector's current implementation, supported configuration features, and installation instructions.

7. The Grand Finale: Five Connectors for AI Engineering Context

This concludes my five-connector Mergetober series for Cognee!

Throughout this series, I explored ways to make different kinds of software engineering context accessible to AI agents.

The common idea behind these contributions is simple: AI agents need access to relevant engineering context, not just general programming knowledge.

An agent that can retrieve information about an application's APIs, database models, container topology, GraphQL schema, and web server configuration has more project-specific evidence to work with when answering questions or proposing changes.

That doesn't remove the need for validation, but it creates a foundation for more context-aware engineering workflows.

A huge thank you to the Cognee team and community for hosting Mergetober and providing an opportunity to contribute to the open-source ecosystem!

Which of these five connectors would be most useful in your engineering stack? Let me know in the comments!