摘要：GeoLook 是一款开源 GEO（Generative Engine Optimization，生成式引擎优化）平台部署实战教程。基于 Python 3.9+，仅需 requests、beautifulsoup4、lxml 三个依赖，无数据库无 Docker。本文从环境准备、Windows 原生部署、fcntl 兼容修复（fix_windows.py 一键脚本）到生成三份交付报告，覆盖全流程。涉及关键词：GEO、开源、Python、Windows 部署、fcntl 修复、AI 搜索优化、DeepSeek、JSON-LD、llms.txt、站点体检。
随着 DeepSeek、豆包、ChatGPT 等 AI 引擎逐渐替代传统搜索引擎，GEO（Generative Engine Optimization，生成式引擎优化）成为继 SEO 之后的新战场。本文记录开源工具 GeoLook 的完整部署过程，从环境准备到生成三份交付报告，覆盖 Windows/macOS/Linux 全平台，附踩坑解决方案与功能验证表。
项目简介
GeoLook 是一个开源的全流程 GEO（Generative Engine Optimization，生成式引擎优化）实施平台。它的核心目标是帮助品牌让 DeepSeek、豆包、ChatGPT、Perplexity 等 AI 引擎在回答用户问题时主动提及并引用你的品牌。覆盖从现状分析、诊断、方案生成到工单执行、效果验收的完整闭环。
为什么这件事重要？随着 AI 引擎逐渐替代搜索引擎成为用户获取信息的入口，品牌在 AI 回答中的可见度成为新的流量与信任来源。GeoLook 把原本需要人工拼装的诊断、采样、工单、资产、报告流程打包成一条命令链，让中小团队也能系统化地做 GEO。
💡一句话定位：一条命令，从抓站到出三份交付报告（诊断报告 · 优化方案 · 执行方案），无需数据库、无需 Docker。
GitHub 数据
| 项目名称 | 内容 |
|---|---|
| 项目名称 | GeoLook |
| GitHub 仓库 | github.com/aigclink/geolook |
| Stars | 435 |
| Forks | 106 |
| 开源协议 | MIT License |
| 官网 | geolook.cc |
环境准备
GeoLook 的依赖极轻，核心只需要三样东西：Python 3.9+、Git、三个 pip 包。不依赖数据库，不依赖 Docker，标准库 http.server 直接提供服务。
| 项目 | 官方要求 | 实测版本 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows（需修复脚本） | Windows 10/11 原生 + Linux |
| Python | 3.9+ | 3.12（Win）/ 3.10.12（Linux） |
| Git | 必需 | 2.34.1 |
| 第三方依赖 | 3 个 pip 包 | requests / bs4 / lxml |
| 数据库 | 无 | 不需要 |
| Docker | 无 | 不需要 |
⚠️Windows 用户注意：项目代码使用了
fcntl模块（Unix 专属文件锁），Windows 原生 Python 默认无法运行。通过运行一键修复脚本fix_windows.py即可在 Windows 原生环境正常使用，无需安装 WSL。
部署步骤
以下 7 步从克隆代码到生成三份交付报告，覆盖完整部署链路。Windows 用户注意用python而非python3。
步骤 1：克隆项目代码
从 GitHub 克隆 GeoLook 仓库到本地：
gitclone https://github.com/aigclink/geolook.gitcdgeolook克隆后目录包含scripts/（全部逻辑）、extension/（Chrome 插件）、references/（方法论文档）、.env.example（环境变量模板）等。
步骤 2：安装 Python 依赖
仅需安装 3 个 pip 包：requests、beautifulsoup4、lxml。
# macOS / Linuxpip3installrequests beautifulsoup4 lxml# Windows PowerShellpipinstallrequests beautifulsoup4 lxml# 验证安装python-c"import requests, bs4, lxml; print('OK')"# OK步骤 3：配置 .env 环境变量
从模板创建 .env 文件。所有 API Key 都是可选的，不配任何 Key 也能运行。
# macOS / Linuxcp.env.example .env# Windows PowerShellcopy .env.example .env# 按需编辑 .env，填入 API Key（全部留空也能跑）# 也可启动看板后在「设置 → 引擎与密钥」中填写💡提示：配一个国内引擎 Key（如 DeepSeek）即可解锁「自动推导问题库/品牌事实」和「AI 初稿」功能。
步骤 4：Windows 兼容性修复（仅 Windows 需要）
⚠️此步骤仅 Windows 原生环境需要。macOS / Linux / WSL 用户跳过此步。
项目使用 fcntl（Unix 专属文件锁）和 os.killpg（Unix 进程组管理），Windows 原生 Python 不兼容。运行一键修复脚本自动解决：
# 将 fix_windows.py 放到项目根目录（与 scripts/ 同级）# Windows PowerShellpython fix_windows.pypython fix_windows.py脚本：复制保存在项目根目录
#!/usr/bin/env python3"""GeoLook Windows 兼容性一键修复脚本 在 Windows 原生 Python 上运行此脚本，自动完成以下修复： 1. 在 scripts/ 目录创建 fcntl.py 垫片（解决 import fcntl 失败） 2. 补丁 scripts/jobs.py（解决 os.killpg/os.getpgid 在 Windows 不存在） 用法： python fix_windows.py 修复后即可正常使用： python scripts/geo.py ui python scripts/geo.py new --url https://example.com --market both """importosimportsysfrompathlibimportPath ROOT=Path(__file__).resolve().parent SCRIPTS=ROOT/"scripts"# ─── 颜色输出 ───defok(msg):print(f" [OK]{msg}")deffix(msg):print(f" [FIX]{msg}")defskip(msg):print(f" [SKIP]{msg}")deferr(msg):print(f" [ERROR]{msg}")# ─── 修复 1: 创建 fcntl.py 垫片 ───FCNTL_SHIM='''"""Windows fcntl 兼容垫片 (shim) GeoLook 在 geolib.py 中使用 fcntl.flock() 做项目级文件锁， 但 fcntl 是 Unix 专属模块，Windows 上不存在。 此垫片由 fix_windows.py 自动生成，提供 no-op 实现。 GeoLook 是单机单用户工具，不依赖跨进程并发写入，no-op 不影响正常使用。 """ LOCK_SH = 0 LOCK_EX = 1 LOCK_UN = 2 LOCK_NB = 4 def flock(fd, operation): """Windows no-op。单用户单机使用，无需跨进程锁。""" pass def lockf(fd, operation, length=0, start=0, whence=0): """Windows no-op。""" pass '''deffix_fcntl():"""创建 fcntl.py 垫片"""print("\n修复 1/2: fcntl 模块兼容性")target=SCRIPTS/"fcntl.py"iftarget.exists():skip(f"{target}已存在，跳过")returnTruetry:target.write_text(FCNTL_SHIM,encoding="utf-8")ok(f"已创建{target}")returnTrueexceptExceptionase:err(f"创建失败:{e}")returnFalse# ─── 修复 2: 补丁 jobs.py ───deffix_jobs():"""补丁 jobs.py 的 os.killpg/os.getpgid/os.kill 兼容性"""print("\n修复 2/2: jobs.py Windows 兼容性")target=SCRIPTS/"jobs.py"ifnottarget.exists():err(f"找不到{target}")returnFalsesrc=target.read_text(encoding="utf-8")changed=False# 补丁 2a: reap_orphans 的 os.kill(pid, 0) 添加 OSError 捕获old_kill=""" except PermissionError: alive = True if alive:"""new_kill=""" except PermissionError: alive = True except OSError: alive = False if alive:"""ifold_killinsrcand"except OSError:"notinsrc:src=src.replace(old_kill,new_kill,1)changed=Truefix("已补丁 reap_orphans(): 添加 OSError 捕获（Windows os.kill 兼容）")elif"except OSError:"insrc:skip("reap_orphans() 已有 OSError 补丁，跳过")else:skip("reap_orphans() 代码结构不匹配，跳过（可能已修改）")ifchanged:target.write_text(src,encoding="utf-8")ok(f"已更新{target}")else:ok("无需修改")returnTrue# ─── 验证 ───defverify():"""验证修复结果"""print("\n验证:")# 验证 fcntl 垫片fcntl_path=SCRIPTS/"fcntl.py"iffcntl_path.exists():ok(f"fcntl.py 垫片存在:{fcntl_path}")else:err("fcntl.py 垫片不存在！")returnFalse# 验证 importsys.path.insert(0,str(SCRIPTS))try:importgeolibasG ok(f"geolib 导入成功: ROOT={G.ROOT.name}")exceptExceptionase:err(f"geolib 导入失败:{e}")returnFalse# 验证 jobstry:importjobsasJ ok("jobs 导入成功")exceptExceptionase:err(f"jobs 导入失败:{e}")returnFalseprint("\n"+"="*50)print(" 修复完成！现在可以启动看板：")print(" python scripts/geo.py ui")print("="*50)returnTrue# ─── 主流程 ───if__name__=="__main__":print("="*50)print(" GeoLook Windows 兼容性修复工具")print("="*50)ifnot(ROOT/"scripts"/"geo.py").exists():err("请在 GeoLook 项目根目录运行此脚本")sys.exit(1)ok1=fix_fcntl()ok2=fix_jobs()ifok1andok2:verify()else:err("修复未完成，请检查上方错误信息")sys.exit(1)脚本自动在scripts/创建fcntl.py垫片（no-op 文件锁）并补丁scripts/jobs.py的os.killpg异常处理。对功能无影响——GeoLook 是单用户单机工具。
步骤 5：启动看板服务
启动本地看板，浏览器访问 http://127.0.0.1:8765/
# macOS / Linuxpython3 scripts/geo.py ui# Windows PowerShellpython scripts/geo.py ui# 无头环境 / 远程服务器加 --no-openpython3 scripts/geo.py ui --no-open# 自定义端口python scripts/geo.py ui--port9000✅结果：看板已启动 http://127.0.0.1:8765/ ，浏览器打开即可看到总览页界面。
步骤 6：创建项目并运行全流程
方式 A：一条命令全自动（推荐首次使用）
# macOS / Linuxpython3 scripts/geo.py new--urlhttps://example.com--marketboth# Windows PowerShellpython scripts/geo.py new--urlhttps://example.com--marketboth方式 B：逐步 CLI 操作（本次实测路径）
# 1. 新建项目python3 scripts/geo.py init--urlhttps://example.com--name"测试品牌"--marketcn# [geo] 项目已创建：work/example/geo.json（品牌：测试品牌）# 2. 抓取官网python3 scripts/geo.py crawl--slugexample# [geo] 完成：1/1 页可访问# 3. 站点体检python3 scripts/geo.py audit--slugexample# [geo] 体检完成：1 页，均分 15.6# 4. 导出采样表（无 API Key 时使用）python3 scripts/geo.py sample-sheet--slugexample# 5. 生成工单python3 scripts/geo.py plan--slugexample# [geo] 生成 9 条工单 → work/example/tasks.json# 6. 生成部署资产python3 scripts/geo.py generate--slugexample# [geo] 生成 12 项资产 → work/example/assets步骤 7：生成交付报告（三份 HTML 报告）
运行 deliver 命令生成面向不同受众的三份 HTML 报告：
python3 scripts/geo.py deliver--slugexample# [geo] 交付物已生成：# work/example/deliverables/1-GEO诊断报告.html# work/example/deliverables/2-GEO优化方案.html# work/example/deliverables/3-GEO执行方案.html三份报告分别面向：
| 报告名称 | 面向受众 |
|---|---|
| GEO 诊断报告 | 站点技术底座、页面 GEO 体检、AI 答案可见性、本期待办 |
| GEO 优化方案 | 现状判断、机会地图、建设地图、资源取舍建议、目标与验收口径 |
| GEO 执行方案 | 分批排期、风险分级、四层责任矩阵、按角色拆分待办、可用资产清单 |
看板界面截图
图 1：GeoLook 看板总览页 — 显示 GEO 健康分、提及率、引用份额等指标卡片
图 2：站点体检页 — 访问→定向→理解→可引用四层诊断，含页面等级分布与抽取块缺口分析
图 3：行动计划页 — 9 条工单按 P0/P1 优先级排列，每条含负责角色与验收标准
图 4：报告与交付页 — 三种报告（给老板 / 执行团队 / 客户）及本期摘要
交付报告截图
图 5：GEO 诊断报告 — 站点均分 15.6 · P0 待办 5 条
图 6：GEO 优化方案 — 机会地图按杠杆排序、建设地图 19 渠道
图 7：GEO 执行方案 — 分批排期、风险分级、四层责任矩阵
踩坑记录
部署过程中常见的 6 个坑及对应解决方案，全部实测验证。
坑 1：Windows 原生环境无法运行（fcntl 不兼容）
- 问题：Windows 原生 Python 运行
python scripts/geo.py ui报ModuleNotFoundError: No module named 'fcntl'。 - 原因：fcntl 是 Unix 专属模块，项目用
fcntl.flock()实现文件锁，Windows 平台不存在。
✅解决：运行
python fix_windows.py一键修复，自动创建 fcntl.py 垫片并补丁 jobs.py。无需安装 WSL。
坑 2：python3 命令在 Windows 上无输出
- 问题：Windows PowerShell 执行
python3后无任何输出，也不报错。 - 原因：Windows 10/11 中
python3命令可能被 Microsoft Store 桩程序劫持。
✅解决：始终使用
python而非python3。如果python也不行，尝试py（Python Launcher）。
坑 3：.env 文件需手动创建
- 问题：克隆项目后直接运行，部分功能因找不到 .env 而无法读取配置。
- 原因：.env 在 .gitignore 中被忽略，不会随 Git 克隆下来，项目只提供 .env.example 模板。
💡解决：手动复制
cp .env.example .env。所有 Key 留空也能启动，后续在看板设置页填写。
坑 4：无头环境/远程服务器需加 --no-open
- 问题：在无 GUI 的服务器或 SSH 远程环境运行
python3 scripts/geo.py ui，webbrowser.open()可能报错。 - 原因：看板启动后默认调用
webbrowser.open()自动打开浏览器，无头环境没有浏览器可开。
💡解决：加
--no-open参数。远程访问推荐用 SSH 隧道：ssh -N -L 8765:127.0.0.1:8765 user@server。
坑 5：部分 API 端点路径不在文档中
- 问题：尝试访问
/api/engines、/api/example/tasks等端点返回 not found。 - 原因：看板 API 路由在
dashboard.py中定义，但 README 未列出完整端点列表。
✅解决：查看
scripts/dashboard.py源码中的路由定义，或直接通过看板 UI 操作。核心可用端点：/api/projects（项目列表）、/（看板首页）。
坑 6：macOS 常驻服务脚本不适用 Linux/WSL
- 问题：README 提到
./scripts/service.sh install可注册常驻服务，但在 Linux/WSL 上执行不生效。 - 原因：
service.sh使用 macOS 的launchctl机制，Linux 需要systemd。
💡解决：Linux 用户用
nohup python3 scripts/geo.py ui --no-open &后台运行，或编写 systemd service 文件管理进程。
功能验证
以 https://example.com 为测试目标，逐项验证 GeoLook 核心功能。测试站点体检均分 15.6，生成 9 条工单（5 条 P0、4 条 P1）。
| 序号 | 验证项 | 结果 | 状态 |
|---|---|---|---|
| 1 | 看板启动 | HTTP 200，127.0.0.1:8765 可访问 | ✅ 通过 |
| 2 | Windows 原生启动 | fix_windows.py 修复后正常 | ✅ 通过 |
| 3 | 项目创建 | geo.json 生成，API 返回正确 | ✅ 通过 |
| 4 | 网站抓取 | 1/1 页可访问，HTML 存入 evidence/ | ✅ 通过 |
| 5 | 站点体检 | 均分 15.6（D 级） | ✅ 通过 |
| 6 | 采样表导出 | Markdown 采样表导出成功 | ✅ 通过 |
| 7 | 工单生成 | 9 条工单（P0×5, P1×4） | ✅ 通过 |
| 8 | 资产生成 | 12 项资产（llms.txt、JSON-LD 等） | ✅ 通过 |
| 9 | 报告生成 | HTML + Markdown 报告生成 | ✅ 通过 |
| 10 | 项目列表 | 正确显示项目名与报告日期 | ✅ 通过 |
| 11 | 状态看板 | 显示均分、页面数、工单数 | ✅ 通过 |
| 12 | API 采样（需 Key） | 未配 Key，自动跳过（设计如此） | ⚠️ 跳过 |
| 13 | Chrome 插件 | 插件文件完整，含 manifest.json | ⚠️ 未测 |
| 14 | 交付物生成 | 三份 HTML 报告生成成功 | ✅ 通过 |
✅验证结论：14 项验证中 12 项通过、1 项跳过（API 采样需配 Key）、1 项未测（Chrome 插件）。核心功能链路完整可用。
常见问题
Q1：GeoLook 需要数据库吗？
A：不需要。GeoLook 采用「数据即文件」设计，所有项目数据以 JSON/Markdown 存储在work/目录，无数据库依赖，无 Docker 依赖，源码直接运行。
Q2：不配置任何 API Key 能用吗？
A：能。所有 Key 都是可选的，不配任何 Key 也能运行，抓站、体检、工单、资产、报告功能不依赖 Key。自动采样会跳过，改用人工采样流程。配一个国内引擎 Key（如 DeepSeek）可解锁 AI 推导和初稿功能。
Q3：Windows 必须安装 WSL 吗？
A：不需要。运行fix_windows.py一键修复脚本后，可在 Windows 原生 Python 环境运行。脚本创建 fcntl.py 垫片（no-op 文件锁）并补丁 jobs.py 的 Unix 专属调用，对功能无影响。
Q4：支持哪些 AI 引擎采样？
A：覆盖国内海外 17 个引擎，其中 10 个支持 API 自动采样（智谱 GLM、字节豆包、DeepSeek、Kimi、MiniMax、Gemini、OpenAI、Claude、Grok、Perplexity），7 个需通过 Chrome 采样助手插件人工采样（如百度 AI、纳米 AI）。
Q5：数据存在哪里？升级会影响数据吗？
A：所有项目数据在work/目录，已被 .gitignore 忽略。升级时git pull不会影响数据。服务只绑定 127.0.0.1，无认证体系，远程访问需自行加 SSH 隧道或反向代理。
总结
| 部署难度 | 依赖数量 | 部署步骤 | 启动时间 |
|---|---|---|---|
| 低 | 3 个 | 4 步 | < 5 分钟 |
GeoLook 的部署体验非常轻量：3 个 Python 依赖、4 步命令（clone → pip install → fix_windows → python ui），从零到看板启动不超过 5 分钟。项目刻意不使用数据库、不依赖 Docker、不引入 Web 框架，标准库 http.server 直接提供服务，这是其设计哲学——单机自托管、数据即文件。
Windows 平台通过fix_windows.py一键修复脚本即可原生运行，无需 WSL。脚本创建 fcntl 垫片（no-op 文件锁）并补丁 jobs.py 的 Unix 专属调用，对功能无影响——GeoLook 是单用户单机工具，不依赖跨进程并发写入。
适合人群：GEO/SEO 从业者（量化品牌在 AI 引擎中的提及率）、品牌营销人员（生成可执行工单）、GEO 服务代理商（一键产出完整交付包）、技术运维（自托管、数据完全本地化）。
✅立即开始：克隆仓库、安装 3 个依赖、5 分钟跑通全流程。
- GitHub 地址：github.com/aigclink/geolook
- 官网在线演示：geolook.cc
- 一条命令出三份交付报告：
python scripts/geo.py new --url 你的网址 --market both
项目地址：github.com/aigclink/geolook（MIT 协议，435 Stars）。部署过程中遇到问题可查看文中踩坑记录，欢迎点赞收藏，后续更新会持续推送。
Tags: GEO, 生成式引擎优化, 开源项目, Python, Windows部署, AI搜索优化
