使用 Ansible 与 Envoy 自动化部署面向 KMP 客户端的 ChromaDB 向量检索服务

DevOps

文章字数: 3.2k

阅读时长: 14 分

Android团队内部的知识孤岛问题日趋严重。CI/CD流水线产生的海量构建日志、内部Wiki上过时的技术文档、以及散落在Slack频道中的解决方案，形成了一个巨大的、非结构化的信息沼泽。当一个开发者遇到一个棘手的编译错误时，他的第一反应通常不是去查询一个统一的知识库，而是在各个频道里@可能知道答案的同事，或者使用关键词在庞杂的日志系统中进行全文搜索，效率极其低下。

问题的核心在于，传统的关键词搜索无法理解语义。开发者搜索“gradle sync failed timeout”时，可能错过了一篇解释“proxy settings for JDK”的解决方案，尽管后者才是根本原因。我们需要一个能够理解“意图”而非“字面”的系统。这自然引向了向量检索技术。

我们的目标是构建一个内部开发者辅助平台（Internal Developer Platform, IDP）的核心组件：一个工程化知识的语义搜索引擎。它必须满足以下几个硬性要求：

自动化部署与管理：整个后端服务必须通过基础设施即代码（IaC）进行管理，避免手动操作带来的不一致性和风险。
架构解耦与可观察性：服务入口必须统一，具备良好的可观察性，且未来易于扩展，例如增加认证、限流等功能。
跨平台客户端支持：开发者应该能通过命令行工具、桌面应用或IDE插件等多种方式接入，而不仅仅是Web界面。

基于这些考量，我们最终确定了如下技术栈：

向量数据库: ChromaDB。它轻量、开源，并且提供HTTP API，非常适合作为我们MVP阶段的引擎。
服务代理: Envoy Proxy。作为所有后端服务的统一入口，提供路由、TLS终止、访问日志、度量指标等能力，将网络逻辑与业务逻辑彻底分离。
自动化工具: Ansible。其Agentless的特性和基于YAML的声明式语法，非常适合用于应用部署和配置管理。
客户端框架: Kotlin Multiplatform (KMP)。一次编码，即可构建出CLI、桌面应用甚至未来Android App中的共享SDK，完美契合跨平台需求。

第一步：使用 Ansible 实现基础设施的自动化部署

我们的第一项任务是编写Ansible Playbook，以实现在目标服务器上自动化部署ChromaDB和Envoy Proxy。在真实项目中，直接在主机上运行容器是一种常见的做法，但配置和依赖管理必须严格自动化。

项目结构如下：

ansible/
├── inventory/
│   └── hosts.ini
├── roles/
│   ├── common/
│   │   └── tasks/
│   │       └── main.yml
│   ├── chromadb/
│   │   └── tasks/
│   │       └── main.yml
│   └── envoy/
│       ├── files/
│       │   └── envoy.yaml
│       └── tasks/
│           └── main.yml
└── playbook.yml

Inventory (inventory/hosts.ini):

[vector_search_server]
192.168.1.100 ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/id_rsa

通用角色 (roles/common/tasks/main.yml):
这个角色负责安装基础依赖，比如Docker。

# roles/common/tasks/main.yml
- name: Update apt cache
  become: yes
  apt:
    update_cache: yes
    cache_valid_time: 3600

- name: Install required system packages
  become: yes
  apt:
    name:
      - apt-transport-https
      - ca-certificates
      - curl
      - software-properties-common
    state: present

- name: Add Docker's official GPG key
  become: yes
  apt_key:
    url: https://download.docker.com/linux/ubuntu/gpg
    state: present

- name: Add Docker repository
  become: yes
  apt_repository:
    repo: "deb [arch=amd64] https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
    state: present

- name: Install Docker
  become: yes
  apt:
    name: docker-ce
    state: present

- name: Ensure docker service is running
  become: yes
  service:
    name: docker
    state: started
    enabled: yes

- name: Install Docker Compose
  become: yes
  pip:
    name: docker-compose
    executable: pip3

ChromaDB 部署角色 (roles/chromadb/tasks/main.yml):
我们使用Docker容器来运行ChromaDB，确保环境隔离和部署一致性。

# roles/chromadb/tasks/main.yml
- name: Ensure ChromaDB data directory exists
  become: yes
  file:
    path: /opt/chromadb_data
    state: directory
    mode: '0755'

- name: Deploy ChromaDB container
  become: yes
  docker_container:
    name: chromadb_service
    image: chromadb/chroma:latest
    state: started
    restart_policy: always
    ports:
      - "127.0.0.1:8000:8000" # 关键：只绑定到localhost，强制流量通过Envoy
    volumes:
      - /opt/chromadb_data:/chroma/.chroma/index
    # 在生产环境中，应考虑使用更复杂的配置，例如设置ANONYMIZED_TELEMETRY=False
    # env:
    #   ANONYMIZED_TELEMETRY: "False"

一个常见的错误是直接将ChromaDB的8000端口暴露给公网。这里的核心安全实践是将其绑定到127.0.0.1，强制所有外部流量必须经过Envoy代理。这为我们后续增加认证、限流等策略提供了唯一的入口点。

Envoy 部署角色 (roles/envoy/tasks/main.yml):
此角色负责部署Envoy容器，并挂载我们的核心配置文件。

# roles/envoy/tasks/main.yml
- name: Create directory for Envoy configuration
  become: yes
  file:
    path: /etc/envoy
    state: directory
    mode: '0755'

- name: Copy Envoy configuration file
  become: yes
  copy:
    src: envoy.yaml
    dest: /etc/envoy/envoy.yaml
    mode: '0644'

- name: Deploy Envoy container
  become: yes
  docker_container:
    name: envoy_proxy
    image: envoyproxy/envoy:v1.27.0
    state: started
    restart_policy: always
    network_mode: "host" # 使用主机网络模式，简化配置，使其能直接访问localhost:8000
    volumes:
      - /etc/envoy/envoy.yaml:/etc/envoy/envoy.yaml
    command: /usr/local/bin/envoy -c /etc/envoy/envoy.yaml

主 Playbook (playbook.yml):
这个文件编排了所有角色，定义了执行流程。

# playbook.yml
- hosts: vector_search_server
  roles:
    - common
    - chromadb
    - envoy

现在，只需执行 ansible-playbook -i inventory/hosts.ini playbook.yml，整个后端基础设施就能被自动化地部署起来。

第二步：配置 Envoy 作为智能流量入口

Envoy的配置是整个架构的核心。它不仅仅是一个反向代理，更是我们服务治理的基石。

Envoy 配置文件 (roles/envoy/files/envoy.yaml):

# roles/envoy/files/envoy.yaml
admin:
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9901 # 管理端口，同样不暴露于公网

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 10000 # 这是对外提供服务的唯一端口
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          access_log:
            - name: envoy.access_loggers.stdout
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  prefix: "/api/v1"
                route:
                  cluster: chromadb_cluster
                  timeout: 5s # 设置合理的超时，防止客户端长时间等待
                  retry_policy:
                    retry_on: "5xx"
                    num_retries: 3
                    per_try_timeout: 2s
              cors:
                allow_origin_string_match:
                  - prefix: "*"
                allow_methods: GET, PUT, DELETE, POST, OPTIONS
                allow_headers: keep-alive,user-agent,cache-control,content-type,content-length,authorization
                max_age: "1728000"

  clusters:
  - name: chromadb_cluster
    connect_timeout: 1s
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: chromadb_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: 127.0.0.1 # Envoy将流量转发至本地的ChromaDB实例
                port_value: 8000

这份配置的几个关键点：

统一入口: 只暴露10000端口，所有请求都必须经过这个Listener。
路由规则: 所有/api/v1前缀的请求都会被路由到名为chromadb_cluster的上游集群。这为未来扩展其他API（如/api/v2或/internal）提供了可能。
韧性设计: 配置了超时（timeout）和重试策略（retry_policy）。当ChromaDB瞬间不可用或返回5xx错误时，Envoy会自动重试3次，增强了系统的健壮性。
可观察性: access_log被配置为输出到标准输出，结合Docker日志驱动，可以轻松地将访问日志集中收集到如ELK或Loki等平台，用于监控和故障排查。
CORS策略: 预先定义了CORS策略，允许来自任何源的请求，这在开发阶段非常方便，生产环境中应收紧为特定的前端域名。

第三步：构建 Kotlin Multiplatform 客户端

KMP的魅力在于，我们可以将所有与网络请求、数据序列化和业务逻辑相关的代码都放在shared模块中，然后为不同平台（Android, Desktop, CLI）编写极薄的UI层。

项目结构 (简化版):

kmp-client/
├── build.gradle.kts
├── settings.gradle.kts
└── shared/
    └── src/
        ├── commonMain/
        │   └── kotlin/
        │       └── com/example/kmpclient/
        │           ├── data/
        │           │   ├── ChromaApi.kt
        │           │   └── models.kt
        │           └── di/
        │               └── KoinModule.kt
        ├── androidMain/
        └── desktopMain/

依赖配置 (shared/build.gradle.kts):

// ...
sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("io.ktor:ktor-client-core:2.3.5")
            implementation("io.ktor:ktor-client-content-negotiation:2.3.5")
            implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.5")
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
        }
    }
    val androidMain by getting {
        dependencies {
            implementation("io.ktor:ktor-client-okhttp:2.3.5")
        }
    }
    val desktopMain by getting {
        dependencies {
            implementation("io.ktor:ktor-client-cio:2.3.5")
        }
    }
}
// ...

数据模型 (shared/src/commonMain/kotlin/.../data/models.kt):
使用kotlinx.serialization定义与ChromaDB API交互的数据结构。

// shared/src/commonMain/kotlin/com/example/kmpclient/data/models.kt
package com.example.kmpclient.data

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonElement

@Serializable
data class QueryRequest(
    val query_texts: List<String>,
    val n_results: Int = 5,
    val include: List<String> = listOf("metadatas", "documents", "distances")
)

@Serializable
data class QueryResult(
    val ids: List<List<String>>,
    val distances: List<List<Double>>?,
    val metadatas: List<List<Metadata?>>,
    val documents: List<List<String?>>
)

@Serializable
data class Metadata(
    val source: String? = null,
    val file_path: String? = null,
    val error_code: String? = null
)

API 客户端实现 (shared/src/commonMain/kotlin/.../data/ChromaApi.kt):
这是核心的网络层。我们使用Ktor，它是一个由JetBrains官方支持的异步网络框架，完美支持KMP。

// shared/src/commonMain/kotlin/com/example/kmpclient/data/ChromaApi.kt
package com.example.kmpclient.data

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.json.Json

class ChromaApi {
    private val httpClient = HttpClient {
        install(ContentNegotiation) {
            json(Json {
                prettyPrint = true
                isLenient = true
                ignoreUnknownKeys = true
            })
        }
    }

    // 在真实项目中，这个URL应该来自配置文件
    private val baseUrl = "http://192.168.1.100:10000"

    suspend fun query(collectionName: String, queryText: String, nResults: Int = 5): Result<QueryResult> {
        return try {
            val response: QueryResult = httpClient.post("$baseUrl/api/v1/collections/$collectionName/query") {
                contentType(ContentType.Application.Json)
                setBody(QueryRequest(query_texts = listOf(queryText), n_results = nResults))
            }.body()
            Result.success(response)
        } catch (e: Exception) {
            // 详尽的错误处理至关重要
            // 在生产代码中，这里应该根据不同的Exception类型（如HttpRequestTimeoutException, NoTransformationFoundException等）进行更细致的处理
            println("Error querying ChromaDB: ${e.message}")
            Result.failure(e)
        }
    }
    
    // 可以添加其他API方法，例如 add, delete, get_collection 等
}

注意这里的错误处理。将网络调用包装在try-catch块中并返回一个Result类型，是Kotlin中处理可能失败操作的健壮模式。这强制调用方必须处理成功和失败两种情况。

在Android ViewModel中使用:
在Android应用中，我们可以直接注入并使用这个ChromaApi。

// In an Android ViewModel
class SearchViewModel(private val chromaApi: ChromaApi) : ViewModel() {

    private val _searchResults = MutableStateFlow<List<String>>(emptyList())
    val searchResults: StateFlow<List<String>> = _searchResults

    fun performSearch(query: String) {
        viewModelScope.launch {
            val result = chromaApi.query("build_errors", query)
            result.onSuccess { queryResult ->
                _searchResults.value = queryResult.documents.flatten().filterNotNull()
            }.onFailure { error ->
                // Handle error state, e.g., show a toast message
                println("Search failed: ${error.localizedMessage}")
            }
        }
    }
}

整体架构与数据流

现在，我们可以清晰地看到整个系统的协同工作方式。

graph TD
    subgraph KMP Client Tier
        A[Android App] --> C{Shared Module};
        B[Desktop/CLI App] --> C;
    end

    subgraph Infrastructure Tier
        D[Envoy Proxy 
 on port 10000] --> E[ChromaDB Container 
 on localhost:8000];
    end
    
    subgraph Automation
        F[Ansible Playbook] -- Deploys & Configures --> D;
        F -- Deploys & Configures --> E;
    end

    C -- HTTP POST /api/v1/collections/.../query --> D;

    style F fill:#f9f,stroke:#333,stroke-width:2px

当一个Android开发者在应用中输入查询时：

Android ViewModel调用KMP shared模块中的ChromaApi.query方法。
ChromaApi通过Ktor发送一个HTTP POST请求到http://192.168.1.100:10000/api/v1/collections/build_errors/query。
请求首先到达服务器上的Envoy代理。
Envoy根据路由规则，匹配到/api/v1前缀，并将请求转发到上游集群chromadb_cluster，即127.0.0.1:8000。
ChromaDB容器接收请求，执行向量相似度搜索，并返回结果。
结果沿原路返回，通过Envoy，最终到达KMP客户端，并在UI上展示。
整个过程中的每一次请求，都会被Envoy记录下详细的访问日志。

局限性与未来迭代路径

这套架构成功地解决了一开始提出的自动化、解耦和跨平台的核心问题，但它只是一个起点。在投入生产环境之前，还有几个方面需要深化：

数据注入管道: 目前我们只关注了查询路径。一个完整的系统需要一个自动化的数据注入管道。这可能涉及到监听CI/CD系统的Webhook，当构建失败时，自动提取日志，使用Sentence Transformer模型将其转换为向量，然后通过API写入ChromaDB。
安全性强化: 当前的Envoy配置是完全开放的。下一步需要集成认证机制，比如使用OAuth2/JWT。Envoy的jwt_authn过滤器可以完美地实现这一点，KMP客户端在请求时带上Token，由Envoy负责验证，无效的请求在到达ChromaDB之前就会被拒绝。
高可用性: ChromaDB和Envoy目前都是单点部署。对于更关键的服务，ChromaDB需要部署为高可用集群。Envoy本身是无状态的，可以水平扩展，前端用一个L4负载均衡器（如NLB）分发流量即可。Ansible Playbook也需要相应地调整以支持多节点部署。
配置管理: 将baseUrl等配置硬编码在代码中是不妥的。这些应该外部化，例如通过KMP客户端启动时加载的配置文件，或者对于Android应用，通过build.gradle中的buildConfigField注入。

Android 开发 ChromaDB Ansible Envoy Proxy Kotlin Multiplatform

构建 GKE 上的多语言可观测性管道：Kotlin、PostgreSQL 与 Matplotlib 协同实现业务指标异常检测

2023-10-27 可观测性

可观测性 PostgreSQL Kotlin Matplotlib GCP GKE

利用 etcd 构建从 GitHub Actions 到 Spinnaker 的 Milvus 可验证安全部署管道

2023-10-27 DevSecOps

GitHub Actions etcd Security Milvus Spinnaker