Maxun 本地安装与配置完全指南从 Docker Compose 到环境变量详解【免费下载链接】maxun The open-source no-code platform for web scraping, crawling, search and AI data extraction • Turn websites into structured APIs in minutes 项目地址: https://gitcode.com/GitHub_Trending/ma/maxunMaxun 是一个开源的免代码网页数据采集平台支持数据抽取Extract、网页抓取Scrape、站点爬取Crawl与搜索Search等能力。本指南以仓库根目录的 SETUP.md 为骨架完整覆盖 Maxun 本地环境搭建的两种方式Docker Compose 与非 Docker 原生安装、全部必需与可选环境变量的含义与取值建议并结合 ENVEXAMPLE、docker-compose.yml 及服务端源码说明底层依赖关系。读完本文你将能够从零搭建一套可用的 Maxun 实例并正确配置数据库、对象存储、浏览器服务与各类外部集成。一、安装前的整体认知Maxun 由哪些服务组成Maxun 不是单一进程而是一套多服务架构。从 docker-compose.yml 可以看到一次完整部署至少包含五个角色服务镜像 / 技术栈职责postgrespostgres:13主数据库存储机器人定义、运行记录、用户账号miniominio/minio对象存储保存 Robot Run 的截图与文件产物redisredis:7缓存/任务队列支撑Docker 编排中按需引入backendgetmaxun/maxun-backend:latestExpress Playwright 后端负责执行采集逻辑frontendgetmaxun/maxun-frontend:latestVite 构建的 React 前端界面browsergetmaxun/maxun-browser:latest独立浏览器容器通过 CDPChrome DevTools Protocol对外提供无头浏览器能力暴露 WebSocket 端口BROWSER_WS_PORT与健康检查端口BROWSER_HEALTH_PORT非 Docker 方式安装时这些服务中的 PostgreSQL、MinIO、Redis 需要你自己在系统层面准备好Maxun 仅负责运行后端与前端两部分Playwright 的 Chromium 浏览器由npx playwright install安装到本机。从源码看后端对缺失配置是硬失败策略server/src/utils/env.ts 中的getEnvVariable会在环境变量缺失时直接抛出Environment variable X is not definedserver/src/db/config/database.js 启动前会校验DB_USER、DB_PASSWORD、DB_NAME、DB_HOST、DB_PORT五个数据库变量缺失即process.exit(1)。因此正确填写.env是安装成功的前提不是可选项。二、方式一使用 Docker Compose 安装推荐这是官方推荐、也是最快的方式整个应用被封装为镜像无需在宿主机安装 Node.js、PostgreSQL 等运行时。操作步骤为你的项目创建一个根目录例如名为maxun的文件夹。在根目录下创建.env文件。参考 ENVEXAMPLE 的全部内容将其复制到你的.env中并替换为符合你环境的值。将 docker-compose.yml 复制到同一根目录。在终端执行docker-compose up -d启动完成后前端地址http://localhost:5173/后端地址http://localhost:8080/关键细节说明docker-compose up -d会依次拉起postgres、minio、backend、frontend和browser服务。backend通过depends_on声明了对postgres、minio的依赖。后端容器内部设置了PLAYWRIGHT_BROWSERS_PATH/ms-playwright、PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD0和CHROMIUM_FLAGS--disable-gpu --no-sandbox --headlessnew保证在容器内正确下载并运行无头 Chromiumsecurity_opt: seccompunconfined与shm_size: 2gb是浏览器在容器中稳定运行的常见规避手段。后端容器设置了mem_limit: 6g与shm_size: 2gb资源约束说明采集任务对内存有一定需求宿主机建议预留足够资源。该 compose 文件中的build段落被注释默认直接从 Docker Hub 拉取getmaxun/maxun-backend:latest、getmaxun/maxun-frontend:latest、getmaxun/maxun-browser:latest三个官方镜像。首次启动时browser容器通过/health端点做健康检查BROWSER_HEALTH_PORT默认 3002。三、方式二不使用 Docker 的原生安装如果你更倾向在宿主机直接运行需要先自行保证以下依赖就绪Node.js后端为 TypeScript/Node 应用前端为 Vite 构建的 React 应用PostgreSQLMinIORedis随后按顺序执行# 克隆仓库 git clone https://github.com/getmaxun/maxun # 进入项目根目录 cd maxun # 安装根目录依赖前端 后端公共依赖 npm install # 进入 maxun-core 安装核心执行引擎依赖 cd maxun-core npm install # 回到根目录 cd .. # 安装 Chromium 及其系统依赖 npx playwright install --with-deps chromium # 回到根目录 cd .. # 同时启动前端与后端 npm run start启动成功后同样通过 http://localhost:5173/前端与 http://localhost:8080/后端访问。这条链路在代码里对应什么结合根目录 package.json 的 scripts 可以理解npm run start实际做了什么start: npm run build:server concurrently -k \npm run server\ \npm run client\先执行tsc -p server/tsconfig.json把 server 目录下的 TypeScript 编译为server/dist再用concurrently并行启动后端node server/dist/server/src/server.js与前端vite。server:dev则提供开发模式nodemon server/src/server.tsvite改动代码可自动重启。maxun-core是独立的包maxun-core/package.json承载采集解释执行的引擎逻辑所以需要单独npm install。四、环境变量全表详解在项目根目录创建.env文件后按 ENVEXAMPLE 逐项填写。下表整理自 SETUP.md 的全部变量并补充了默认值与推荐取值标注来自 ENVEXAMPLE的示例值可直接复制变量是否必填说明未设置时的后果 / 默认值BACKEND_PORT是后端运行端口Docker 场景必须设置默认 8080FRONTEND_PORT是前端运行端口Docker 场景必须设置默认 5173BACKEND_URL是后端对外访问 URL默认 http://localhost:8080VITE_BACKEND_URL是前端用来连接后端的 URL应与BACKEND_URL保持一致默认 http://localhost:8080PUBLIC_URL是前端对外访问 URL默认 http://localhost:5173VITE_PUBLIC_URL是后端用来回调前端的 URL应与PUBLIC_URL保持一致默认 http://localhost:5173JWT_SECRET是用于签名与校验 JWT 的密钥JWT 认证不可用DB_NAME是PostgreSQL 数据库名示例maxun数据库连接失败DB_USER是PostgreSQL 用户名示例postgres数据库连接失败DB_PASSWORD是PostgreSQL 密码数据库连接失败DB_HOST是PostgreSQL 主机地址Docker 内为服务名postgres数据库连接失败DB_PORT是PostgreSQL 端口默认 5432数据库连接失败ENCRYPTION_KEY是用于加密敏感数据代理配置、密码的密钥加密功能不可用SESSION_SECRET否签名 session cookie 的强随机字符串使用默认密钥官方建议自定义以防 session 劫持MINIO_ENDPOINT是MinIO 端点用于存储 Robot Run 截图Docker 内为服务名minio连接 MinIO 存储失败MINIO_PORT是MinIO 服务端口默认 9000连接 MinIO 存储失败MINIO_CONSOLE_PORT否MinIO WebUI 端口默认 9001Docker 场景需要无法访问 MinIO Web 界面MINIO_ACCESS_KEY是MinIO 访问密钥MinIO 认证失败GOOGLE_CLIENT_ID否Google OAuth Client ID用于 Google Sheet 集成认证Google 登录不可用GOOGLE_CLIENT_SECRET否Google OAuth Client SecretGoogle 登录不可用GOOGLE_REDIRECT_URI否Google OAuth 回调 URIGoogle 登录不可用AIRTABLE_CLIENT_ID否Airtable Client ID用于 Airtable 集成认证Airtable 登录不可用AIRTABLE_REDIRECT_URI否Airtable OAuth 回调 URIAirtable 登录不可用MAXUN_TELEMETRY否匿名使用数据遥测开关官方建议保持开启以便改进产品关闭后不再采集遥测数据注意SETUP.md 的环境变量表中未单独列出MINIO_SECRET_KEY、REDIS_*、BROWSER_WS_*等变量但它们在 ENVEXAMPLE 与 docker-compose.yml 中确实被使用以下一并补充说明避免照抄示例时遗漏。补充变量ENVEXAMPLE 中出现但 SETUP.md 表中未列出的项变量说明NODE_ENV运行环境development或productionMINIO_SECRET_KEYMinIO 访问密钥的密钥部分示例minio_secret_keycompose 中映射为MINIO_ROOT_PASSWORDMINIO_PUBLIC_URL可选。当 MinIO 位于反向代理之后或使用非 localhost/非 9000 的公网地址时浏览器通过该地址访问截图/文件例如https://storage.example.comREDIS_HOSTRedis 主机Docker 内为服务名redisREDIS_PORTRedis 端口默认 6379REDIS_PASSWORDRedis 密码可选设置了密码的实例需要填写否则留空直连BROWSER_WS_PORT浏览器容器对外 CDP WebSocket 端口默认 3001BROWSER_HEALTH_PORT浏览器容器健康检查端口默认 3002BROWSER_WS_HOST浏览器 WebSocket 主机名Docker 内为服务名browser生产部署的密钥生成建议SETUP.md 与 docs/self-hosting-docker.md 都强调JWT_SECRET、DB_PASSWORD、ENCRYPTION_KEY、SESSION_SECRET等敏感值务必替换为随机强密钥不要使用示例值。可以使用以下命令生成# 生成随机的 JWT_SECRET / SESSION_SECRET48 字节 base64 openssl rand -base64 48 # 生成随机的数据库密码 / MinIO 密钥24 字节 base64 openssl rand -base64 24 # 生成加密密钥64 字节 base64 openssl rand -base64 64自托管文档中的.env模板正是采用这一策略JWT_SECRETopenssl rand -base64 48等并且特别提示部署前务必通读.env并按实际环境修改变量例如把BACKEND_PORT改为非默认值如30000以避免端口冲突。五、常见配置场景与排错要点1. 端口/URL 不一致导致前后端连不上VITE_BACKEND_URL必须与BACKEND_URL保持一致、VITE_PUBLIC_URL必须与PUBLIC_URL保持一致ENVEXAMPLE 中有明确注释。如果前端页面能打开但请求后端报错优先检查这两对变量是否成对配置。2. 数据库连接失败按 server/src/db/config/database.js五个DB_*变量任一缺失都会在启动时直接退出。另支持DB_SSLtrue开启 PostgreSQL SSL 连接ssl: { require: true, rejectUnauthorized: false }自建/云数据库启用 SSL 时可设置该项。3. 截图/文件访问不到MinIO 相关变量不全会导致存储连接失败若使用了反向代理且 MinIO 不在 localhost:9000 上需要设置MINIO_PUBLIC_URL参见 ENVEXAMPLE 注释。4. 浏览器容器无法启动可检查BROWSER_WS_PORT、BROWSER_HEALTH_PORT、BROWSER_WS_HOST是否与 compose 中的端口映射一致browser服务的健康检查通过curl http://localhost:${BROWSER_HEALTH_PORT}/health判断若宿主机缺少该端口映射采集会异常。5. 安装方式与升级路径使用 Docker Compose 时升级只需更新镜像后重新docker-compose up -d官方文档中对应 Upgrade Maxun With Docker Compose Setup 路径。数据库迁移命令在根目录 package.json 中暴露npm run migratesequelize-cli db:migrate迁移文件位于 server/src/db/migrations。六、进阶生产级自托管与反向代理如果要在公网服务器上提供 Maxun 服务推荐参考 docs/self-hosting-docker.md将 Maxun 仅绑定到127.0.0.1由 Nginx 等反向代理统一对外暴露 HTTPS。该方案的核心要点准备子域名如maxun.my.domain、Web 服务器Apache2/nginx、SSL 证书Lets Encrypt 等与 Docker/Docker Compose。为服务建独立目录并做好数据持久化db、minio、redis子目录挂载到容器。编写.env时把BACKEND_URL、PUBLIC_URL、VITE_BACKEND_URL、VITE_PUBLIC_URL全部设为你的公网域名如https://maxun.my.domain。该自托管 compose 中backend与frontend的端口均绑定127.0.0.1保证只有 localhost 可访问外部流量必须经反向代理。完整的 Nginx 配置模板见 docs/nginx.conf它同时处理了两类流量后端与 WebSocket 流量location ~ ^/(auth|storage|record|workflow|robot|proxy|api-docs|api|webhook|socket.io)(/|$)转发到http://localhost:8080对应.env的BACKEND_PORT并设置Upgrade/Connection头以支持socket.io实时通信前端流量location /转发到http://localhost:5173对应FRONTEND_PORT。模板还包含了 HTTP 301 跳转 HTTPS、TLSv1.2/TLSv1.3、gzip 压缩与安全响应头X-Frame-Options、X-Content-Type-Options等等生产级配置client_max_body_size 512M保证了较大的上传与文件请求不被拦截。七、小结一份可复用的最小.env模板综合 SETUP.md、ENVEXAMPLE 与自托管文档本地 Docker 部署的最小可用.env如下敏感值请替换NODE_ENVproduction JWT_SECRET强随机字符串 DB_NAMEmaxun DB_USERpostgres DB_PASSWORD强随机字符串 DB_HOSTpostgres DB_PORT5432 ENCRYPTION_KEY强随机字符串 SESSION_SECRET强随机字符串 MINIO_ENDPOINTminio MINIO_PORT9000 MINIO_CONSOLE_PORT9001 MINIO_ACCESS_KEYminio_access_key MINIO_SECRET_KEY强随机字符串 # MINIO_PUBLIC_URLhttps://storage.example.com # 仅在 MinIO 走反向代理/非本机地址时需要 REDIS_HOSTredis REDIS_PORT6379 # REDIS_PASSWORD BACKEND_PORT8080 FRONTEND_PORT5173 BACKEND_URLhttp://localhost:8080 PUBLIC_URLhttp://localhost:5173 VITE_BACKEND_URLhttp://localhost:8080 VITE_PUBLIC_URLhttp://localhost:5173 # 可选Google Sheet / Airtable 集成 # GOOGLE_CLIENT_ID # GOOGLE_CLIENT_SECRET # GOOGLE_REDIRECT_URI # AIRTABLE_CLIENT_ID # AIRTABLE_REDIRECT_URI MAXUN_TELEMETRYtrue填写完成后把 docker-compose.yml 放到同一目录并执行docker-compose up -d即可在 http://localhost:5173 使用自己的 Maxun 实例。需要排查细节时可对照 SETUP.md、ENVEXAMPLE 与 docs/self-hosting-docker.md 逐项核对。【免费下载链接】maxun The open-source no-code platform for web scraping, crawling, search and AI data extraction • Turn websites into structured APIs in minutes 项目地址: https://gitcode.com/GitHub_Trending/ma/maxun创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考