可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本指南讲解 PhoenixAI 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。它一次拉起一组互相配合的容器构成接近生产形态的完整调试闭环服务镜像 / 构建来源作用对外端口traefiktraefik:v3.6.2统一反向代理按路径把请求分发到各服务18273:80phoenix本地构建DockerfilePhoenix 主应用暴露 6006/4317/9090经 Traefik 暴露dbpostgres:17-alpinePostgreSQL 17 数据库Phoenix 与 OIDC 服务器共用5433:5433oidc-dev本地构建oidc-server/Dockerfile完全符合 OpenID Connect 1.0 规范的调试身份服务器经 Traefik 暴露smtp-dev本地构建smtp-server/Dockerfile假 SMTP 服务器 Web 邮件查看界面经 Traefik 暴露vite-dev本地构建vite-dev/DockerfileVite 前端开发服务器仅viteProfile 启用5173prometheus/grafana/postgres-exporter/cadvisor官方镜像监控链路仅grafanaProfile 启用9187 等toxiproxy/toxiproxy-initshopify/toxiproxy数据库网络故障模拟仅toxiproxyProfile 启用8474核心服务默认全部常驻不依赖 Profile 即启动vite-dev、监控组件、Toxiproxy 与 LDAP 相关服务则由 Compose Profile 按需启用。三个关键访问入口环境启动后所有 Web 服务都通过 Traefik 聚合在同一个端口18273下按路径前缀区分Phoenixhttp://localhost:18273/phoenix/SMTP 邮件查看界面http://localhost:18273/mail/PostgreSQL 数据库localhost:5433账号密码均为postgrespostgres/postgres数据库端口与常用 5432 错开为 5433避免与宿主机上可能已运行的本地 PostgreSQL 冲突这是该环境特意做的端口隔离设计。二、快速启动两条等价入口原文档给出的最快路径是借助项目根目录的 tox 配置执行# 启动全部服务最常用 tox r -e docker_devops # 停止全部服务 tox r -e docker_devops -- downdocker_devops这个 tox 环境的底层动作就是调用devops目录下的 dev.sh 脚本——--之后的部分会被透传给该脚本作为参数down即对应./dev.sh down。仓库根目录的 Makefile 也提供了等价入口# Makefile 入口默认执行 dev.sh up make dev-docker # 传参等价于 ./dev.sh down make dev-docker ARGSdown两种方式殊途同归读者可根据个人习惯选择。若不使用 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 每个命令的语义与适用场景原文档用一张决策表总结了选择逻辑你的情况该用哪个命令语义说明只改了代码Python / TS 业务代码tox r -e docker_devops即up复用已构建镜像增量重建并启动速度最快依赖发生变化pyproject.toml、uv.lock、package.json等tox r -e docker_devops -- rebuildDOCKER_BUILDKIT1 docker-compose build --no-cache全量重建之后up -d --force-recreate强制重建容器需要全新数据数据库/监控数据都要重置tox r -e docker_devops -- destroy停止容器并删除devops_前缀的全部数据卷PostgreSQL、Grafana、Prometheus 数据此操作不可逆脚本会二次确认从 dev.sh 的实现看各命令的底层动作分别为updocker-compose up -d后台拉起 → 等待 Phoenix 健康检查通过 → 打印服务地址rebuildbuild --no-cache借助 BuildKit→up -d --force-recreate→ 同样的健康检查等待down通过labelcom.docker.compose.projectdevops找到并停止、删除该项目全部容器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 schemamyapp # 自定义 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 7636PKCE支持标准授权码流程与 PKCE 流程。通过不同 Profile 可切换客户端认证方式pkce-publicpkce-public.ymlPhoenix 侧设置PHOENIX_OAUTH2_DEV_USE_PKCEtrue、清空 client secret、TOKEN_ENDPOINT_AUTH_METHODnone并开启groupsscope 与phoenix-admins等组白名单Grafana 同步切到 PKCE 公共客户端模式pkce-confidential保留 client secretPhoenix 与 OIDC 服务器均以机密客户端 PKCE 方式认证。Grafana 的 OIDC 接入默认在grafanaProfile 中即已启用client idgrafana-oidc-client-id通过GF_AUTH_GENERIC_OAUTH_*系列变量与 OIDC 服务器打通实现「登录 Phoenix 后免登录进入 Grafana」。5.3 基础认证与数据库模式basic-auth/in-memorybasic-authbasic-auth.yml仅把PHOENIX_DISABLE_BASIC_AUTH置为false恢复用户名/密码登录in-memoryin-memory.yml将db服务副本数降为 0并把PHOENIX_SQL_DATABASE_URL改为sqlite:///:memory:彻底免掉 PostgreSQL适合快速跑前端或单测类场景。5.4 监控链路grafanagrafanaProfile 一次性拉起四个监控组件见 docker-compose.ymlprometheusprom/prometheus:v3.1.0抓取配置见 prometheus.yml每 15 秒抓取phoenix:9090/metrics、postgres-exporter:9187、cadvisor:8080以及自身grafanagrafana/grafana:11.4.0数据源与仪表盘通过 grafana/provisioning 自动预置其中仪表盘模板在 phoenix-simple-monitoring.jsonpostgres-exporterprometheuscommunity/postgres-exporter:v0.16.0暴露9187采集 PostgreSQL 指标cadvisorgcr.io/cadvisor/cadvisor:v0.51.0privileged 模式采集容器运行时指标。Phoenix 主服务在PHOENIX_ENABLE_PROMETHEUStrue下暴露 9090 端口的 Prometheus 指标。Grafana 访问入口同样挂在 Traefik 下http://localhost:18273/grafana。5.5 网络故障模拟toxiproxytoxiproxyProfile 在 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账号adminexample.com/ 密码admin_password用 ldap-seed.ldif 等种子文件预置用户、组数据在 Phoenix 侧注入一整套PHOENIX_LDAP_*环境变量PHOENIX_LDAP_HOSTldap、PHOENIX_LDAP_BIND_DNcnreadonly,...、PHOENIX_LDAP_USER_SEARCH_FILTER(uid%s)、PHOENIX_LDAP_ATTR_MEMBER_OFmemberOf以及PHOENIX_LDAP_GROUP_ROLE_MAPPINGS把 LDAP 组映射为 Phoenix 角色如cnadmins→ADMIN三个变体分别覆盖标准 email 模式、无邮箱用户按entryUUID标识身份、POSIX 组模式GROUP_SEARCH_FILTERmemberUid不依赖memberOf。5.7 动态 SchemaschemaNAME这是 dev.sh 特有的动态 Profile参数形式为--profile schemamyapp。脚本会校验 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.dockertrue且exposedbydefaultfalse仅显式打标traefik.enabletrue的服务才会被路由。以 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_dataPostgreSQL 数据dev_prometheus_data/dev_grafana_data监控数据dev_cursor_server_dataPhoenix 容器内 VS Code 远程开发Cursor Server数据。这正是destroy能「一键清空所有数据」的原因——它删除的正是devops_前缀的这些命名卷。6.3 镜像构建三段式 DockerfilePhoenix 服务镜像由 Dockerfile 构建采用三段结构Frontend Buildernode:24-slim拷贝整个js/pnpm workspace 与schemas/pnpm install --frozen-lockfile后按拓扑序构建phoenix-ui前端产物Backend Builderpython:3.13-slim-bullseye用uv按pyproject.tomluv.lock安装依赖缓存友好随后uv build构建 Python wheel 并安装同时把 site-packages 扁平化复制到/phoenix/env消除版本路径差异此阶段还会预下载 CPython WASM 沙箱运行时校验 SHA-256与捆绑 Deno 沙箱二进制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在容器内核实变量值作用PHOENIX_SQL_DATABASE_URLpostgresql://postgres:postgresdb:5433/postgres数据库连接PHOENIX_ENABLE_PROMETHEUStrue暴露 Prometheus 指标PHOENIX_HOST_ROOT_PATH/PHOENIX_ROOT_URL/phoenix/http://localhost:18273/phoenix子路径部署PHOENIX_ENABLE_AUTH/PHOENIX_DISABLE_BASIC_AUTHtrue/true强制 OIDC 认证PHOENIX_OAUTH2_DEV_*见编排文件开发用 OIDC 客户端配置PHOENIX_SMTP_*localhost:1025等接入内置假 SMTP 服务器数据库容器postgres:17-alpine也做了开发向调优shared_preload_librariespg_stat_statements、max_connections200、shared_buffers256MB、checkpoint_completion_target0.9等并启用--data-checksums初始化与pg_isready健康检查。七、典型工作流速查场景推荐命令首次启动 / 日常开发改代码tox r -e docker_devops依赖变更后启动tox r -e docker_devops -- rebuild停止环境tox r -e docker_devops -- down彻底重置数据tox r -e docker_devops -- destroy前端热更新开发./dev.sh up --profile vite验证 PKCE 登录链路./dev.sh up --profile pkce-public打开监控面板./dev.sh up --profile grafanaGrafana 在http://localhost:18273/grafana测试 LDAP 登录./dev.sh up --profile ldapLDAP 管理台http://localhost:6443模拟数据库故障./dev.sh up --profile toxiproxy排查环境变量./dev.sh env \| grep DATABASE这套环境的完整清单、Profile 说明与命令帮助随时可用./dev.sh help查看仓库内还附有 k8s 下的 OIDC sidecar 部署示例与 LDAP-TLS-TESTING.md含 test_ldap_integration.py 等测试脚本可作为将本地调试结论迁移到 Kubernetes 或 TLS 生产环境的参考。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐OneUptime 本地开发环境搭建基于 docker-compose.dev.yml 的全栈调试指南OneUptime 本地开发环境搭建基于 docker compose.dev.yml 的全栈调试指南 本篇指南基于 OneUptime 官方文档中的「Loc可观测性后端运维前端云原生微服务AI AgentLago 本地开发环境搭建实战Docker Compose、Traefik TLS 与多服务调试指南Lago 本地开发环境搭建实战Docker Compose、Traefik TLS 与多服务调试指南 本指南以 Lago 仓库的 docs/dev_envir后端金融科技LunaTranslator 新手指南5 步跑通视觉小说游戏内实时翻译LunaTranslator 新手指南5 步跑通视觉小说游戏内实时翻译 LunaTranslator 是一个和游戏同时运行的视觉小说翻译工具玩到外文台词的瞬桌面应用OCR人工智能上一篇LinkSwift网盘直链解析工具告别限速实现高速下载自由下一篇3步实现B站UP主动态视频自动下载高效智能的4K视频保存方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Phoenix 本地开发环境搭建指南：基于 Docker Compose 的 Traefik + PostgreSQL + OIDC + 监控一体化调试栈
可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本指南讲解 PhoenixAI 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。它一次拉起一组互相配合的容器构成接近生产形态的完整调试闭环服务镜像 / 构建来源作用对外端口traefiktraefik:v3.6.2统一反向代理按路径把请求分发到各服务18273:80phoenix本地构建DockerfilePhoenix 主应用暴露 6006/4317/9090经 Traefik 暴露dbpostgres:17-alpinePostgreSQL 17 数据库Phoenix 与 OIDC 服务器共用5433:5433oidc-dev本地构建oidc-server/Dockerfile完全符合 OpenID Connect 1.0 规范的调试身份服务器经 Traefik 暴露smtp-dev本地构建smtp-server/Dockerfile假 SMTP 服务器 Web 邮件查看界面经 Traefik 暴露vite-dev本地构建vite-dev/DockerfileVite 前端开发服务器仅viteProfile 启用5173prometheus/grafana/postgres-exporter/cadvisor官方镜像监控链路仅grafanaProfile 启用9187 等toxiproxy/toxiproxy-initshopify/toxiproxy数据库网络故障模拟仅toxiproxyProfile 启用8474核心服务默认全部常驻不依赖 Profile 即启动vite-dev、监控组件、Toxiproxy 与 LDAP 相关服务则由 Compose Profile 按需启用。三个关键访问入口环境启动后所有 Web 服务都通过 Traefik 聚合在同一个端口18273下按路径前缀区分Phoenixhttp://localhost:18273/phoenix/SMTP 邮件查看界面http://localhost:18273/mail/PostgreSQL 数据库localhost:5433账号密码均为postgrespostgres/postgres数据库端口与常用 5432 错开为 5433避免与宿主机上可能已运行的本地 PostgreSQL 冲突这是该环境特意做的端口隔离设计。二、快速启动两条等价入口原文档给出的最快路径是借助项目根目录的 tox 配置执行# 启动全部服务最常用 tox r -e docker_devops # 停止全部服务 tox r -e docker_devops -- downdocker_devops这个 tox 环境的底层动作就是调用devops目录下的 dev.sh 脚本——--之后的部分会被透传给该脚本作为参数down即对应./dev.sh down。仓库根目录的 Makefile 也提供了等价入口# Makefile 入口默认执行 dev.sh up make dev-docker # 传参等价于 ./dev.sh down make dev-docker ARGSdown两种方式殊途同归读者可根据个人习惯选择。若不使用 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 每个命令的语义与适用场景原文档用一张决策表总结了选择逻辑你的情况该用哪个命令语义说明只改了代码Python / TS 业务代码tox r -e docker_devops即up复用已构建镜像增量重建并启动速度最快依赖发生变化pyproject.toml、uv.lock、package.json等tox r -e docker_devops -- rebuildDOCKER_BUILDKIT1 docker-compose build --no-cache全量重建之后up -d --force-recreate强制重建容器需要全新数据数据库/监控数据都要重置tox r -e docker_devops -- destroy停止容器并删除devops_前缀的全部数据卷PostgreSQL、Grafana、Prometheus 数据此操作不可逆脚本会二次确认从 dev.sh 的实现看各命令的底层动作分别为updocker-compose up -d后台拉起 → 等待 Phoenix 健康检查通过 → 打印服务地址rebuildbuild --no-cache借助 BuildKit→up -d --force-recreate→ 同样的健康检查等待down通过labelcom.docker.compose.projectdevops找到并停止、删除该项目全部容器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 schemamyapp # 自定义 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 7636PKCE支持标准授权码流程与 PKCE 流程。通过不同 Profile 可切换客户端认证方式pkce-publicpkce-public.ymlPhoenix 侧设置PHOENIX_OAUTH2_DEV_USE_PKCEtrue、清空 client secret、TOKEN_ENDPOINT_AUTH_METHODnone并开启groupsscope 与phoenix-admins等组白名单Grafana 同步切到 PKCE 公共客户端模式pkce-confidential保留 client secretPhoenix 与 OIDC 服务器均以机密客户端 PKCE 方式认证。Grafana 的 OIDC 接入默认在grafanaProfile 中即已启用client idgrafana-oidc-client-id通过GF_AUTH_GENERIC_OAUTH_*系列变量与 OIDC 服务器打通实现「登录 Phoenix 后免登录进入 Grafana」。5.3 基础认证与数据库模式basic-auth/in-memorybasic-authbasic-auth.yml仅把PHOENIX_DISABLE_BASIC_AUTH置为false恢复用户名/密码登录in-memoryin-memory.yml将db服务副本数降为 0并把PHOENIX_SQL_DATABASE_URL改为sqlite:///:memory:彻底免掉 PostgreSQL适合快速跑前端或单测类场景。5.4 监控链路grafanagrafanaProfile 一次性拉起四个监控组件见 docker-compose.ymlprometheusprom/prometheus:v3.1.0抓取配置见 prometheus.yml每 15 秒抓取phoenix:9090/metrics、postgres-exporter:9187、cadvisor:8080以及自身grafanagrafana/grafana:11.4.0数据源与仪表盘通过 grafana/provisioning 自动预置其中仪表盘模板在 phoenix-simple-monitoring.jsonpostgres-exporterprometheuscommunity/postgres-exporter:v0.16.0暴露9187采集 PostgreSQL 指标cadvisorgcr.io/cadvisor/cadvisor:v0.51.0privileged 模式采集容器运行时指标。Phoenix 主服务在PHOENIX_ENABLE_PROMETHEUStrue下暴露 9090 端口的 Prometheus 指标。Grafana 访问入口同样挂在 Traefik 下http://localhost:18273/grafana。5.5 网络故障模拟toxiproxytoxiproxyProfile 在 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账号adminexample.com/ 密码admin_password用 ldap-seed.ldif 等种子文件预置用户、组数据在 Phoenix 侧注入一整套PHOENIX_LDAP_*环境变量PHOENIX_LDAP_HOSTldap、PHOENIX_LDAP_BIND_DNcnreadonly,...、PHOENIX_LDAP_USER_SEARCH_FILTER(uid%s)、PHOENIX_LDAP_ATTR_MEMBER_OFmemberOf以及PHOENIX_LDAP_GROUP_ROLE_MAPPINGS把 LDAP 组映射为 Phoenix 角色如cnadmins→ADMIN三个变体分别覆盖标准 email 模式、无邮箱用户按entryUUID标识身份、POSIX 组模式GROUP_SEARCH_FILTERmemberUid不依赖memberOf。5.7 动态 SchemaschemaNAME这是 dev.sh 特有的动态 Profile参数形式为--profile schemamyapp。脚本会校验 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.dockertrue且exposedbydefaultfalse仅显式打标traefik.enabletrue的服务才会被路由。以 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_dataPostgreSQL 数据dev_prometheus_data/dev_grafana_data监控数据dev_cursor_server_dataPhoenix 容器内 VS Code 远程开发Cursor Server数据。这正是destroy能「一键清空所有数据」的原因——它删除的正是devops_前缀的这些命名卷。6.3 镜像构建三段式 DockerfilePhoenix 服务镜像由 Dockerfile 构建采用三段结构Frontend Buildernode:24-slim拷贝整个js/pnpm workspace 与schemas/pnpm install --frozen-lockfile后按拓扑序构建phoenix-ui前端产物Backend Builderpython:3.13-slim-bullseye用uv按pyproject.tomluv.lock安装依赖缓存友好随后uv build构建 Python wheel 并安装同时把 site-packages 扁平化复制到/phoenix/env消除版本路径差异此阶段还会预下载 CPython WASM 沙箱运行时校验 SHA-256与捆绑 Deno 沙箱二进制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在容器内核实变量值作用PHOENIX_SQL_DATABASE_URLpostgresql://postgres:postgresdb:5433/postgres数据库连接PHOENIX_ENABLE_PROMETHEUStrue暴露 Prometheus 指标PHOENIX_HOST_ROOT_PATH/PHOENIX_ROOT_URL/phoenix/http://localhost:18273/phoenix子路径部署PHOENIX_ENABLE_AUTH/PHOENIX_DISABLE_BASIC_AUTHtrue/true强制 OIDC 认证PHOENIX_OAUTH2_DEV_*见编排文件开发用 OIDC 客户端配置PHOENIX_SMTP_*localhost:1025等接入内置假 SMTP 服务器数据库容器postgres:17-alpine也做了开发向调优shared_preload_librariespg_stat_statements、max_connections200、shared_buffers256MB、checkpoint_completion_target0.9等并启用--data-checksums初始化与pg_isready健康检查。七、典型工作流速查场景推荐命令首次启动 / 日常开发改代码tox r -e docker_devops依赖变更后启动tox r -e docker_devops -- rebuild停止环境tox r -e docker_devops -- down彻底重置数据tox r -e docker_devops -- destroy前端热更新开发./dev.sh up --profile vite验证 PKCE 登录链路./dev.sh up --profile pkce-public打开监控面板./dev.sh up --profile grafanaGrafana 在http://localhost:18273/grafana测试 LDAP 登录./dev.sh up --profile ldapLDAP 管理台http://localhost:6443模拟数据库故障./dev.sh up --profile toxiproxy排查环境变量./dev.sh env \| grep DATABASE这套环境的完整清单、Profile 说明与命令帮助随时可用./dev.sh help查看仓库内还附有 k8s 下的 OIDC sidecar 部署示例与 LDAP-TLS-TESTING.md含 test_ldap_integration.py 等测试脚本可作为将本地调试结论迁移到 Kubernetes 或 TLS 生产环境的参考。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐OneUptime 本地开发环境搭建基于 docker-compose.dev.yml 的全栈调试指南OneUptime 本地开发环境搭建基于 docker compose.dev.yml 的全栈调试指南 本篇指南基于 OneUptime 官方文档中的「Loc可观测性后端运维前端云原生微服务AI AgentLago 本地开发环境搭建实战Docker Compose、Traefik TLS 与多服务调试指南Lago 本地开发环境搭建实战Docker Compose、Traefik TLS 与多服务调试指南 本指南以 Lago 仓库的 docs/dev_envir后端金融科技LunaTranslator 新手指南5 步跑通视觉小说游戏内实时翻译LunaTranslator 新手指南5 步跑通视觉小说游戏内实时翻译 LunaTranslator 是一个和游戏同时运行的视觉小说翻译工具玩到外文台词的瞬桌面应用OCR人工智能上一篇LinkSwift网盘直链解析工具告别限速实现高速下载自由下一篇3步实现B站UP主动态视频自动下载高效智能的4K视频保存方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
