快速开始#
前置条件#
- Docker 与 Docker Compose
- （生产环境）一台 2C4G 以上的服务器
1. 克隆并启动#
git clone https://github.com/aak1247/logtap.git
cd logtap/deploy
# 生成 AUTH_SECRET（base64，解码后 >= 32 字节）
bash ../scripts/gen-auth-secret.sh
# 启动，自带 Postgres/TimescaleDB、Redis、NSQ
docker compose up -d启动后：
- 网关与控制台：
http://localhost:8080 - NSQ Admin：
http://localhost:4171 - Postgres：
localhost:5432（默认库logtap）
docker-compose.yml 已包含 TimescaleDB、Redis、NSQ（lookupd/nsqd/admin）与 logtap 网关，约 1 分钟即可就绪。也可以先在在线演示控制台体验。
2. 开启鉴权后的访问方式#
设置了 AUTH_SECRET 后：
- 控制台需要登录
- 上报必须携带项目 Key：
X-Project-Key: pk_...（项目页可创建），或 Sentry SDK 的sentry_key
PowerShell 环境可用 powershell -ExecutionPolicy Bypass -File scripts/gen-auth-secret.ps1，或 Taskfile 的 task auth:secret。
3. 发出第一条日志#
先在控制台创建项目，拿到项目 ID 与 pk_ 开头的项目 Key：
curl -X POST http://localhost:8080/api/1/logs/ \
-H "Content-Type: application/json" \
-H "X-Project-Key: pk_xxx" \
-d '{
"level": "info",
"message": "hello logtap",
"user": { "id": "u1" },
"fields": { "env": "dev" }
}'返回 202 Accepted 即入队成功。回到控制台即可看到这条日志，并可以继续尝试：
- 搜索：日志页关键词检索
- 埋点：
POST /api/1/track/上报事件后查看 DAU、漏斗与留存 - 异常：把任意 Sentry SDK 的 DSN 指到 LogTap，见Sentry 兼容
可选：启用 GeoIP#
需要 MaxMind GeoLite2 下载密钥：在 .env 中设置 MAXMIND_LICENSE_KEY，Compose 会把 mmdb 下载并缓存到 volume /data/geoip/，用于来源国家/城市/ASN 分布分析。