企业官网建设流程全解析

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能

本指南讲解 Phoenix（AI Observability & Evaluation 平台）仓库自带的 Docker Compose 开发环境（scripts/docker/devops）的完整搭建与使用：它以 Traefik 反向代理统一入口，内置 PostgreSQL、OIDC 调试服务器、SMTP 假邮件服务器，并可一键启用 Grafana/Prometheus 监控、LDAP 认证、Toxiproxy 网络故障模拟等可插拔 Profile。读完本文，你将掌握通过tox/dev.sh快速启动、重建、销毁这套环境的全部命令，理解各服务之间的路由与依赖关系，并能针对「改代码、改依赖、换认证方案、测故障注入」等典型开发场景选择正确的命令组合。

一、环境总览：这套开发栈里有什么

该开发环境位于仓库的 scripts/docker/devops 目录，其核心编排文件是 docker-compose.yml。它一次拉起一组互相配合的容器，构成接近生产形态的完整调试闭环：

核心服务默认全部常驻（不依赖 Profile 即启动）；vite-dev、监控组件、Toxiproxy 与 LDAP 相关服务则由 Compose Profile 按需启用。

三个关键访问入口

环境启动后，所有 Web 服务都通过 Traefik 聚合在同一个端口18273下，按路径前缀区分：

• Phoenix：http://localhost:18273/phoenix/
• SMTP 邮件查看界面：http://localhost:18273/mail/
• PostgreSQL 数据库：localhost:5433，账号密码均为postgres（postgres/postgres）

数据库端口与常用 5432 错开为 5433，避免与宿主机上可能已运行的本地 PostgreSQL 冲突，这是该环境特意做的端口隔离设计。

二、快速启动：两条等价入口

原文档给出的最快路径是借助项目根目录的 tox 配置执行：

# 启动全部服务（最常用） tox r -e docker_devops # 停止全部服务 tox r -e docker_devops -- down

docker_devops这个 tox 环境的底层动作就是调用devops目录下的 dev.sh 脚本——--之后的部分会被透传给该脚本作为参数（down即对应./dev.sh down）。仓库根目录的 Makefile 也提供了等价入口：

# Makefile 入口：默认执行 dev.sh up make dev-docker # 传参：等价于 ./dev.sh down make dev-docker ARGS=down

两种方式殊途同归，读者可根据个人习惯选择。若不使用 tox / make，也可以直接进入目录执行脚本（见下文第三节）。

启动过程值得注意：dev.sh up在拉起容器后会主动轮询 Phoenix 的健康检查端点http://localhost:18273/phoenix/healthz（超时 60 秒），并在第 15 次检查未通过时自动输出phoenix容器最近 100 行日志辅助排障；若在日志中检测到exception/traceback/phoenix.exceptions关键字，会直接判定启动失败并提示执行./dev.sh destroy && ./dev.sh up重来。这意味着脚本对启动失败做了自动诊断，无需手动docker logs排查。

三、命令体系：Tox 包装 vs 直接脚本

3.1 Tox 包装命令

tox r -e docker_devops # 重建镜像 + 启动（默认动作，改代码后用它） tox r -e docker_devops -- rebuild # 全量重建（最慢，依赖变更时用） tox r -e docker_devops -- down # 停止全部服务 tox r -e docker_devops -- destroy # 核弹选项（清空所有数据！）

3.2 直接使用 dev.sh（等价关系）

./dev.sh up # 等价于 tox r -e docker_devops ./dev.sh rebuild # 等价于 tox r -e docker_devops -- rebuild ./dev.sh down # 等价于 tox r -e docker_devops -- down ./dev.sh destroy # 等价于 tox r -e docker_devops -- destroy

注意：以上命令都要在scripts/docker/devops目录下执行。dev.sh会先做依赖检查（要求宿主机已安装docker与docker-compose，缺失时直接报错退出），再按set -e严格模式执行。

3.3 每个命令的语义与适用场景

原文档用一张决策表总结了选择逻辑：

从 dev.sh 的实现看，各命令的底层动作分别为：

• up：docker-compose up -d后台拉起 → 等待 Phoenix 健康检查通过 → 打印服务地址；
• rebuild：build --no-cache（借助 BuildKit）→up -d --force-recreate→ 同样的健康检查等待；
• down：通过label=com.docker.compose.project=devops找到并停止、删除该项目全部容器；
• destroy：先down，再查找并删除devops_前缀的 Docker 数据卷，真正实现「数据归零」。

destroy是「核弹选项」，执行前脚本会输出This will permanently delete all database data!并要求输入y确认，这是对误操作的最后一道防线。

四、扩展命令：dev.sh 的完整工具箱

原文档只列举了四个基本命令，但仓库中的 dev.sh 实际提供了更完整的运维子命令，用于日常开发的磁盘与镜像管理：

./dev.sh up # 启动（默认） ./dev.sh rebuild # 全量重建镜像（依赖变更） ./dev.sh down # 停止服务 ./dev.sh reset # 删除本项目全部镜像（下次 up 时重建） ./dev.sh destroy # 清空数据卷（数据库、Grafana、Prometheus） ./dev.sh prune # 清理 Docker 构建缓存（释放磁盘） ./dev.sh clean # 全量 Docker 清理（警告：会删掉 Docker 里的一切！） ./dev.sh status # 查看运行状态与当前 Profile ./dev.sh profiles # 列出可用 Profile ./dev.sh env # 导出 Phoenix 容器内全部 PHOENIX_ 前缀环境变量

决策建议：

• 磁盘吃紧 →./dev.sh prune（仅清理构建缓存），或./dev.sh clean（全量清理，需慎重）；
• 需要确认当前配置 →./dev.sh status/./dev.sh env；
• ./dev.sh env | grep DATABASE可快速核对容器内实际生效的数据库连接配置。

其中env子命令会在 Phoenix 容器运行时，用docker exec提取并排序所有PHOENIX_前缀环境变量——这是排查环境变量是否真正生效的最直接手段。

五、Profile 体系：按需组合的开发场景

dev.sh的一个核心设计是Profile 机制：通过--profile/--profiles参数，把身份认证方案、前端模式、数据库类型、监控与故障注入等能力做成了可插拔组合，无需修改主编排文件。

./dev.sh up --profile vite # 启用 Vite 前端开发服务器 ./dev.sh up --profile pkce-public # PKCE 公共客户端（无 client secret） ./dev.sh up --profile pkce-confidential # PKCE 机密客户端（带 client secret） ./dev.sh up --profile basic-auth # 基础认证（用户名/密码） ./dev.sh up --profile in-memory # 内存 SQLite 数据库 ./dev.sh up --profile toxiproxy # 启用网络故障模拟 ./dev.sh up --profile grafana # 启用 Grafana + Prometheus 监控 ./dev.sh up --profile ldap # 启用 LDAP 认证（mock LDAP 服务器） ./dev.sh up --profile ldap-no-email # LDAP 认证（用户无邮箱，按 entryUUID 识别） ./dev.sh up --profile ldap-posix # LDAP 认证（POSIX 组，无 memberOf） ./dev.sh up --profile schema=myapp # 自定义 PostgreSQL schema（数据库名） ./dev.sh up --profiles vite,grafana # 多个 Profile 组合（逗号分隔）

各 Profile 的机制与作用如下（对应 overrides 目录中的覆盖文件）：

5.1 前端开发模式：vite

默认的Dockerfile是「生产模式」三段构建：先构建前端静态资源打进镜像，不运行开发服务器。启用viteProfile 后，phoenix 服务改用 Dockerfile.vite，并拉起独立的vite-dev容器（内存上限 4G、CPU 8 核），通过 vite.yml 覆盖构建方式，把宿主机js/app目录以缓存卷方式挂载进容器，实现前端代码的热更新开发。

5.2 OIDC 认证模式：pkce-public/pkce-confidential

内置的 OIDC 调试服务器（oidc-server）实现了 OpenID Connect Core 1.0 与 RFC 7636（PKCE），支持标准授权码流程与 PKCE 流程。通过不同 Profile 可切换客户端认证方式：

• pkce-public（pkce-public.yml）：Phoenix 侧设置PHOENIX_OAUTH2_DEV_USE_PKCE=true、清空 client secret、TOKEN_ENDPOINT_AUTH_METHOD=none，并开启groupsscope 与phoenix-admins等组白名单；Grafana 同步切到 PKCE 公共客户端模式；
• pkce-confidential：保留 client secret，Phoenix 与 OIDC 服务器均以机密客户端 + PKCE 方式认证。

Grafana 的 OIDC 接入默认在grafanaProfile 中即已启用（client idgrafana-oidc-client-id），通过GF_AUTH_GENERIC_OAUTH_*系列变量与 OIDC 服务器打通，实现「登录 Phoenix 后免登录进入 Grafana」。

5.3 基础认证与数据库模式：basic-auth/in-memory

• basic-auth（basic-auth.yml）：仅把PHOENIX_DISABLE_BASIC_AUTH置为false，恢复用户名/密码登录；
• in-memory（in-memory.yml）：将db服务副本数降为 0，并把PHOENIX_SQL_DATABASE_URL改为sqlite:///:memory:，彻底免掉 PostgreSQL，适合快速跑前端或单测类场景。

5.4 监控链路：grafana

grafanaProfile 一次性拉起四个监控组件（见 docker-compose.yml）：

• prometheus（prom/prometheus:v3.1.0），抓取配置见 prometheus.yml：每 15 秒抓取phoenix:9090/metrics、postgres-exporter:9187、cadvisor:8080以及自身；
• grafana（grafana/grafana:11.4.0），数据源与仪表盘通过 grafana/provisioning 自动预置（其中仪表盘模板在 phoenix-simple-monitoring.json）；
• postgres-exporter（prometheuscommunity/postgres-exporter:v0.16.0）暴露9187采集 PostgreSQL 指标；
• cadvisor（gcr.io/cadvisor/cadvisor:v0.51.0，privileged 模式）采集容器运行时指标。

Phoenix 主服务在PHOENIX_ENABLE_PROMETHEUS=true下暴露 9090 端口的 Prometheus 指标。Grafana 访问入口同样挂在 Traefik 下：http://localhost:18273/grafana。

5.5 网络故障模拟：toxiproxy

toxiproxyProfile 在 Phoenix 与数据库之间插入ghcr.io/shopify/toxiproxy:2.11.0代理，可对数据库链路注入延迟、丢包、连接中断等故障，用于验证 Phoenix 的容错与重试逻辑。初始化容器 setup-toxiproxy.sh 会自动创建指向db:5433的代理；仓库还提供了现成故障剧本脚本 toxiproxy-scenario.sh（支持 latency / timeout / down 等场景），配合jq可查看当前注入的 toxics。

5.6 LDAP 认证：ldap/ldap-no-email/ldap-posix

三个 LDAP Profile 均基于 ldap.yml 派生：

• 拉起osixia/openldap:1.5.0服务（端口 389/636）与phpldapadmin管理界面（http://localhost:6443，账号admin@example.com/ 密码admin_password）；
• 用 ldap-seed.ldif 等种子文件预置用户、组数据；
• 在 Phoenix 侧注入一整套PHOENIX_LDAP_*环境变量：PHOENIX_LDAP_HOST=ldap、PHOENIX_LDAP_BIND_DN=cn=readonly,...、PHOENIX_LDAP_USER_SEARCH_FILTER=(uid=%s)、PHOENIX_LDAP_ATTR_MEMBER_OF=memberOf，以及PHOENIX_LDAP_GROUP_ROLE_MAPPINGS把 LDAP 组映射为 Phoenix 角色（如cn=admins→ADMIN）；
• 三个变体分别覆盖：标准 email 模式、无邮箱用户（按entryUUID标识身份）、POSIX 组模式（GROUP_SEARCH_FILTER+memberUid，不依赖memberOf）。

5.7 动态 Schema：schema=NAME

这是 dev.sh 特有的动态 Profile：参数形式为--profile schema=myapp。脚本会校验 schema 名（非空、不超过 63 字符、以字母或下划线开头、仅含合法字符、且不是 PostgreSQL 保留关键字），校验通过后动态生成一个临时 override 文件，写入PHOENIX_SQL_DATABASE_SCHEMA=$schema_name，实现多租户 Schema 隔离场景下的开发测试。

提示：--profile传单值，--profiles传逗号分隔的多个值；所有 Profile 都会映射到对应的 override 文件与 Compose--profile标志，./dev.sh profiles可随时查看完整清单。

六、架构与源码级细节

6.1 Traefik 统一路由

Traefik 容器暴露18273:80，通过 Docker socket 自动发现服务（providers.docker=true且exposedbydefault=false，仅显式打标traefik.enable=true的服务才会被路由）。以 Phoenix 为例，路由规则为：

Host(`localhost`) && PathPrefix(`/phoenix/`)

并叠加stripprefix中间件剥掉/phoenix前缀再转发到 6006 端口；同时另配一条/.well-known/前缀路由不剥前缀直接转发，保证 OAuth 发现文档（RFC 8414/9728 的 well-known 路径）能被 MCP 等客户端在宿主根路径下正常探测。OIDC（/oidc）、SMTP 邮件界面（/mail）、Grafana（/grafana）、Vite（/phoenix/vite）各自都有独立的路由与 strip 中间件。

6.2 服务依赖与数据持久化

phoenix容器通过depends_on等待oidc-dev与smtp-dev就绪后才启动；oidc-dev又依赖db。数据持久化由四个命名卷承担：

• dev_database_data：PostgreSQL 数据；
• dev_prometheus_data/dev_grafana_data：监控数据；
• dev_cursor_server_data：Phoenix 容器内 VS Code 远程开发（Cursor Server）数据。

这正是destroy能「一键清空所有数据」的原因——它删除的正是devops_前缀的这些命名卷。

6.3 镜像构建：三段式 Dockerfile

Phoenix 服务镜像由 Dockerfile 构建，采用三段结构：

1. Frontend Builder（node:24-slim）：拷贝整个js/pnpm workspace 与schemas/，pnpm install --frozen-lockfile后按拓扑序构建phoenix-ui前端产物；
2. Backend Builder（python:3.13-slim-bullseye）：用uv按pyproject.toml+uv.lock安装依赖（缓存友好），随后uv build构建 Python wheel 并安装，同时把 site-packages 扁平化复制到/phoenix/env（消除版本路径差异）；此阶段还会预下载 CPython WASM 沙箱运行时（校验 SHA-256）与捆绑 Deno 沙箱二进制；
3. Runtime：合成前端产物与 Python 环境，写入 VS Code 调试配置（launch.json监听 5678 端口），最终以 start-phoenix.sh 为入口命令——该脚本负责把localhost:18273转发到 Traefik、localhost:1025转发到 SMTP，然后以python -m debugpy --listen 0.0.0.0:5678 -m phoenix.server.main serve启动带调试器的 Phoenix 服务。

6.4 预置的 Phoenix 环境变量

主编排文件为 Phoenix 预置了完整的运行配置，开发时可通过./dev.sh env在容器内核实：

数据库容器（postgres:17-alpine）也做了开发向调优：shared_preload_libraries=pg_stat_statements、max_connections=200、shared_buffers=256MB、checkpoint_completion_target=0.9等，并启用--data-checksums初始化与pg_isready健康检查。

七、典型工作流速查

这套环境的完整清单、Profile 说明与命令帮助，随时可用./dev.sh help查看；仓库内还附有 k8s 下的 OIDC sidecar 部署示例与 LDAP-TLS-TESTING.md（含 test_ldap_integration.py 等测试脚本），可作为将本地调试结论迁移到 Kubernetes 或 TLS 生产环境的参考。

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能