Refine Devtools 企业版配置指南：自定义端口与 Docker 自定义域名部署

Refine Devtools 企业版配置指南自定义端口与 Docker 自定义域名部署【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineRefine Devtools 是 Refine 框架提供的开发调试工具可帮助开发者监控应用的查询与变更queries/mutations、检查组件发起的请求并一键升级依赖。本文基于 Refine 仓库中的企业版文档 documentation/docs/enterprise-edition/devtools/index.md系统讲解如何通过REFINE_DEVTOOLS_PORT环境变量自定义 Devtools 服务器端口以及如何在 Docker 中将应用与 Devtools 服务器分离部署并使用自定义域名访问。读完本文你将掌握 Devtools 端口/域名的完整配置链路从 CLI 到DevtoolsProvider /组件并能直接照抄一套可运行的 docker-compose 多容器方案。为什么需要自定义端口与域名企业版的差异化能力社区版的 Refine Devtools 在refine dev启动时默认运行在5001端口且只在开发模式development下生效生产构建不会将其打进 bundle、不影响应用性能参见 documentation/docs/guides-concepts/development/index.md。而企业版Enterprise Edition在此基础上放开了两项能力修改 Devtools 服务器的端口不再被锁定在默认的5001为 Devtools 服务器使用自定义域名适用于把应用与 Devtools 服务器分别容器化Docker 化的场景也适用于在多个 Refine 应用中共享同一个 Devtools 服务器的情况。社区版存在端口限制官方文档明确说明在5001以外的端口运行 Refine Devtools 仅在企业版中可用社区版下修改端口后 Devtools 将无法工作见 documentation/docs/guides-concepts/development/index.md。因此在采用自定义端口或自定义域名前请先确认你使用的是企业版。指定 Devtools 服务器端口REFINE_DEVTOOLS_PORT启动 Devtools 服务器有两种方式它们都会尊重REFINE_DEVTOOLS_PORT环境变量使用refinedev/cli提供的refine devtools start命令使用refinedev/devtools-server包提供的独立命令如refine-devtools。修改端口只需把REFINE_DEVTOOLS_PORT环境变量设置为目标端口号即可。例如在refine dev时指定端口5002REFINE_DEVTOOLS_PORT5002 refine dev环境变量的读取链路源码验证refinedev/devtools-server在启动时就会读取该环境变量来决定监听端口。在 packages/devtools-server/src/constants.ts 中可以看到const RAW_ENV_REFINE_DEVTOOLS_PORT process.env.REFINE_DEVTOOLS_PORT || refineEnv.REFINE_DEVTOOLS_PORT; export const DEFAULT_SERVER_PORT 5001; export const SERVER_PORT Number(RAW_ENV_REFINE_DEVTOOLS_PORT) || DEFAULT_SERVER_PORT;其中refineEnv来自dotenv.config也就是说该变量既可以写在 shell 环境里也可以写进项目的.env文件。refinedev/cli侧同样通过 dotenv 兼容两种来源见 packages/cli/src/utils/env/index.ts。refine dev自动传播端口给前端应用当在refine dev命令中设置了REFINE_DEVTOOLS_PORTCLI 会把端口值自动传播给你的应用并暴露为对应平台的前端环境变量供浏览器端读取。其实现位于 packages/cli/src/commands/runner/dev/index.tsconst devtoolsPortEnvKey getDevtoolsEnvKeyByProjectType(projectType); // ... const envWithDevtoolsPort devtools ENV.REFINE_DEVTOOLS_PORT ? { [devtoolsPortEnvKey]: ENV.REFINE_DEVTOOLS_PORT } : undefined; runScript(binPath, command, envWithDevtoolsPort);getDevtoolsEnvKeyByProjectType会根据项目平台把端口写入对应前缀的环境变量见 packages/cli/src/utils/project/index.ts项目平台注入的前端环境变量Create React Appreact-scriptsREACT_APP_REFINE_DEVTOOLS_PORTNext.jsNEXT_PUBLIC_REFINE_DEVTOOLS_PORTViteVITE_REFINE_DEVTOOLS_PORT其他/默认REFINE_DEVTOOLS_PORTDevtoolsProvider /组件会自动使用上述任一环境变量来拼接 Devtools 服务器的 HTTP 与 WebSocket 地址。相关实现见 packages/devtools/src/utilities/get-devtools-url-from-env.tsconst DEFAULT_DEVTOOLS_PORT 5001; export const getDevtoolsUrlFromEnv () { const PORT_FROM_ENV /* 依次读取 REFINE_DEVTOOLS_PORT、NEXT_PUBLIC_REFINE_DEVTOOLS_PORT、REACT_APP_REFINE_DEVTOOLS_PORT、VITE_REFINE_DEVTOOLS_PORT */; const port PORT_FROM_ENV || DEFAULT_DEVTOOLS_PORT; return [http://localhost:${port}, ws://localhost:${port}] as [ httpUrl: string, wsUrl: string, ]; };可以看到返回的是一个[httpUrl, wsUrl]二元组——Devtools 服务器需要同时承载 HTTP 连接用于 UI 界面和 WebSocket 连接用于实时推送数据因此自定义端口时两个协议会共用同一端口。手动指定连接地址DevtoolsProvider urlprop如果环境变量在浏览器端没有生效例如浏览器环境无法读取构建期的环境变量或者你想使用自定义域名可以在DevtoolsProvider /组件中通过urlprop 手动指定 Devtools 服务器地址import Refine from refinedev/core; import { DevtoolsProvider, DevtoolsPanel } from refinedev/devtools; const App () { return ( DevtoolsProvider // highlight-next-line urlhttp://refine-devtools.local Refine {/* ... */} DevtoolsPanel / /Refine /DevtoolsProvider ); };从 packages/devtools/src/provider.tsx 的源码可以看到urlprop 的完整类型与默认行为type Props React.PropsWithChildren{ url?: string | [httpUrl: string, wsUrl: string]; }; export const DevtoolsProvider __DEV_CONDITION__ ! development ? ({ children }: Props) children as any : ({ children, url getDevtoolsUrlFromEnv() }: Props) ( DevToolsContextProvider url{url}{children}/DevToolsContextProvider );要点url接受字符串如http://refine-devtools.local或[httpUrl, wsUrl]二元组当 HTTP 与 WebSocket 地址不同时使用未传url时默认调用getDevtoolsUrlFromEnv()即用环境变量端口构造http://localhost:port与ws://localhost:port通过构建期常量__DEV_CONDITION__判断仅在 development 模式下才会真正提供上下文生产模式下组件直接透传 children、不产生任何副作用。使用 Docker 与自定义域名分离部署完整实战下面演示如何把 Refine 应用与 Refine Devtools分别容器化并分别通过http://my-app.local与http://devtools.local访问。完整示例代码来自关联文档所引用的 documentation/docs/enterprise-edition/devtools/docker.tsx该文件以 Sandpack 内联代码的形式给出了全部配置文件。1. 应用侧的依赖与脚本在package.json中声明两个脚本dev用于启动应用开发服务器注意通过--devtools false关闭 CLI 的自动 Devtools 启动因为我们要单独运行 Devtools 容器devtools用于启动独立的 Devtools 服务器{ name: my-app, version: 1.0.0, private: true, type: module, scripts: { dev: refine dev --devtools false -- --host, devtools: refine devtools, refine: refine }, dependencies: { refinedev/cli: ^2.16.36, refinedev/core: ^4.53.0, refinedev/devtools: ^1.2.6 } }关于--devtools false如果你通过refine devtools start手动管理 Devtools 服务器那么在用refine dev启动应用时应传入--devtoolsfalse标志来禁止 CLI 自动拉起 Devtools 服务器见 documentation/docs/guides-concepts/development/index.md。2. 应用容器Dockerfile.dev应用开发服务器运行在5173端口后续由 Nginx 反向代理# 使用官方 Node.js 镜像作为基础镜像 FROM refinedev/node # 复制 package.json 与 package-lock.json COPY package*.json ./ # 安装依赖 RUN npm install # 复制应用其余代码 COPY . . # 暴露应用运行端口 EXPOSE 5173 # 启动开发服务器的命令 CMD [npm, run, dev]3. Devtools 服务器容器Dockerfile.devtoolsDevtools 服务器运行在5001端口# 使用 Refine 的 Node.js 镜像作为基础镜像 FROM refinedev/node COPY package*.json ./ RUN npm install COPY . . # 暴露 devtools 服务器端口 EXPOSE 5001 # 启动 devtools 服务器的命令 CMD [npm, run, devtools]4. 编排两个容器docker-compose.ymldev与devtools两个服务共享命名卷app注意匿名卷/app/refine/node_modules避免宿主机覆盖容器内依赖并共同挂在dev-network桥上网络nginx作为入口对外暴露80端口version: 3 services: dev: build: context: . dockerfile: Dockerfile.dev volumes: - app:/app/refine - /app/refine/node_modules networks: - dev-network devtools: build: context: . dockerfile: Dockerfile.devtools volumes: - app:/app/refine - /app/refine/node_modules networks: - dev-network nginx: image: nginx:latest ports: - 80:80 volumes: - ./nginx.conf:/etc/nginx/nginx.conf networks: - dev-network networks: dev-network: driver: bridge volumes: app:5. 反向代理配置nginx.confNginx 根据请求的Hostserver_name把流量分别转发到两个容器events { worker_connections 1024; } http { server { listen 80; server_name my-app.local; location / { proxy_pass http://dev:5173; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } server { listen 80; server_name devtools.local; location / { proxy_pass http://devtools:5001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } }6. 应用侧接入自定义域名应用组件中只需把DevtoolsProvider /的url指向 Devtools 域名即可其余工作全部由refinedev/devtools包处理import { Refine } from refinedev/core; import { DevtoolsProvider, DevtoolsPanel } from refinedev/devtools; export default function App() { return ( DevtoolsProvider urlhttp://devtools.local Refine {/* ... */} DevtoolsPanel / /Refine /DevtoolsProvider ); }7. 本地域名解析更新/etc/hosts为了让浏览器把两个域名解析到本机需要在/etc/hosts中添加127.0.0.1 my-app.local 127.0.0.1 devtools.local完成后即可分别在 Docker 容器中运行 Refine 应用与 Refine Devtools并通过自定义域名连接 Devtools 服务器。整个过程中应用侧只需要修改App.tsx中url这一行其余的域名路由、容器通信与 WebSocket 转发都由refinedev/devtools与上述 Nginx 配置接管。常见问题与注意事项为什么url需要同时承载 HTTP 与 WebSocket从getDevtoolsUrlFromEnv的实现看Devtools 服务器同一端口同时提供 HTTPUI 界面与 WebSocket实时数据推送服务使用反向代理时需确保 WebSocket 升级请求也能被转发生产环境建议补充Upgrade/Connection头配置。refine dev自动启动与手动启动如何取舍默认情况下只要安装了refinedev/devtoolsrefine dev就会自动拉起 Devtools 服务器手动管理时用refine dev --devtoolsfalse关闭自动启动并用refine devtools start单独启动见 documentation/docs/guides-concepts/development/index.md。环境变量不生效时怎么办优先检查浏览器端是否读取到了对应平台前缀的变量Vite 为VITE_REFINE_DEVTOOLS_PORT、Next.js 为NEXT_PUBLIC_REFINE_DEVTOOLS_PORT、CRA 为REACT_APP_REFINE_DEVTOOLS_PORT否则直接在DevtoolsProvider url...中硬编码地址即可。仅限开发模式DevtoolsProvider在非 development 构建下直接透传 children不会带来任何运行时开销但也不要指望在生产环境中使用 Devtools 面板。小结本文完整覆盖了 Refine 企业版 Devtools 的两项核心自定义能力通过REFINE_DEVTOOLS_PORT修改服务器端口并经由 CLI 自动注入到前端环境变量、被DevtoolsProvider /消费以及通过urlprop 对接自定义域名。结合 Docker 分离部署的完整示例你可以在多应用共享 Devtools、容器化开发环境等真实场景中直接复用这套配置。若要进一步了解 Devtools 的通用能力与安装方式可参考 开发指南中的 Devtools 章节 与 refinedev/devtools 包源码。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考