Address 部署与安装指南：自托管真实地址生成器 | 极客的赛博空间

Address 是一个基于 PostgreSQL 的、自托管的真实住宅地址生成器。它的地址数据来自官方开放数据、国家或地区地址登记册、地图注册建筑等，并保留了原始坐标，可在地图服务中定位。支持多语言输出、IP 附近生成、地图预览和 JSON API 调用。

1. 系统要求

在开始部署前，请确保您的服务器满足以下要求：

操作系统：Linux (推荐 Ubuntu/Debian) 或 macOS。
Docker 和 Docker Compose：这是推荐且最简单的部署方式。
PostgreSQL：如果不用 Docker，需要单独安装并配置（版本 14+ 推荐）。
Node.js：版本 18.x 或 20.x（用于源码运行，Docker 方式无需）。
硬件：至少 2GB 内存，地址数据同步需要一定的存储空间（视同步的国家数量而定）。

2. 快速部署（推荐使用 Docker）

这是最快、最可靠的方式，所有依赖（包括 PostgreSQL）都在容器中运行。

2.1 克隆仓库

1 2	git clone https://github.com/daimon3332/address.git cd address

2.2 初始化并启动服务

项目提供了便捷的初始化脚本：

1 2	sh ops/init-compose.sh docker compose up -d

init-compose.sh 脚本会检查环境并生成必要的配置文件。
docker compose up -d 会在后台启动 API 服务、PostgreSQL 数据库等所有需要的容器。

2.3 验证部署

启动完成后，访问以下地址验证服务是否正常运行：

健康检查：http://你的服务器IP:端口/api/health (默认端口可能为 3000 或 80，具体查看 docker-compose.yml 配置)
Web 界面：http://你的服务器IP:端口

3. 手动部署（不使用 Docker）

如果您希望在没有 Docker 的环境下运行，可以按以下步骤操作。

3.1 环境准备

安装 Node.js (>=18) 和 npm。
安装并运行 PostgreSQL (>=14)，并创建一个空数据库（例如 address_db）。
安装 Git。

3.2 克隆并安装依赖

1
2
3

git clone https://github.com/daimon3332/address.git
cd address
npm install

3.3 配置环境变量

复制示例环境变量文件并编辑：

1	cp .env.example .env

在 .env 文件中，至少需要配置以下核心数据库连接信息：

1	DATABASE_URL=postgresql://用户名:密码@localhost:5432/address_db

其他可选配置包括 API 端口、密钥等，请根据注释按需修改。

3.4 初始化数据库并同步地址数据

项目需要从开放数据源同步地址信息到本地数据库。

bash

# 运行数据库迁移（如果有）
npm run db:migrate

# 启动地址数据同步（这将花费一些时间，取决于网络和数据量）
npm run sync

3.5 启动应用

# 开发模式
npm run dev

# 生产模式（建议使用进程管理工具如 pm2）
npm run build
npm start

应用默认运行在 http://localhost:3000。

4. 初始配置与使用

4.1 访问 Web 界面

部署成功后，通过浏览器访问应用地址。您将看到地址生成器的前端界面，可以：

选择国家和地区。
按行政区域、城市、邮政编码等进行过滤。
生成真实地址（包含门牌号、街道、城市、坐标等）。
将地址收藏到浏览器本地，并分组管理。
在地图（Google Maps 或 AMap）上预览地址位置。

4.2 管理员控制台

首次使用需要设置管理员账户（通过命令行或配置文件创建）。
管理员可以：

监控数据覆盖度：查看各国地址数据的同步状态和完整性。
管理地址数据规则：配置数据源、同步策略。
管理 API 令牌：生成和管理用于 API 调用的访问令牌。
查看同步队列和历史：监控数据同步任务的执行情况。

4.3 使用 JSON API

Address 提供了丰富的 JSON API，可用于程序化调用。所有 API 请求需使用 Bearer Token 认证。
API 基础路径：/api

获取支持的国家列表：GET /api/countries
获取某国的可用地址选项：GET /api/availability?country=US
生成单个地址：GET /api/generate?country=US&format=zh-CN
批量生成地址：POST /api/generate-batch (请求体包含 count 和过滤参数)
健康检查：GET /api/health

Python 调用示例：

import requests

url = "http://localhost:3000/api/generate"
params = {
    "country": "CN",
    "format": "zh-CN",
    "city": "Beijing"
}
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

5. 自动化数据同步

Address 的核心是其自动化数据同步机制。系统会从配置的开放数据源拉取地址数据，经过验证和清洗后存入 PostgreSQL。

同步策略：每个国家/地区有独立的同步规则，包括源地址、证据门控（确保是住宅地址）、最小覆盖要求等。
同步队列：系统使用有界重试、指数退避、断点续传等机制，确保同步任务的健壮性。
监控：在管理员控制台的 “Data monitor” 页面，可以直观地看到每个国家的同步状态、记录数和覆盖度。
优先级：中国 (CN) 数据源在同步队列中拥有最高的自动优先级。

6. 常见问题排查

问题	可能原因	解决方案
`docker compose up -d` 启动失败	端口冲突或 Docker 环境未就绪	检查 `docker-compose.yml` 中的端口映射是否被占用，确保 Docker 服务已启动。
访问 Web 界面显示空白或错误	环境变量未正确配置或 API 服务未就绪	确认 `.env` 文件中的 `DATABASE_URL` 等关键变量正确，并检查 API 容器日志。
地址数据无法同步（生成地址时返回空）	数据同步未完成或源数据访问受限	1. 在管理员控制台查看同步状态。 2. 检查服务器网络是否能访问开放数据源（如 Overture Maps、Geofabrik）。 3. 查看同步任务日志获取具体错误。
API 调用返回 401 Unauthorized	缺少或无效的 API Token	在管理员控制台生成有效的 API Token，并在请求头中正确添加 `Authorization: Bearer <TOKEN>`。
数据库连接错误	PostgreSQL 未运行或 `DATABASE_URL` 不正确	确认 PostgreSQL 服务已启动，并验证 `.env` 中的连接字符串（主机、端口、用户名、密码、数据库名）。

7. 总结

Address 是一个数据驱动、功能完善的自托管地址生成服务。

核心部署路径：

使用 Docker（推荐）：git clone → sh ops/init-compose.sh → docker compose up -d。
手动部署：安装 Node.js 和 PostgreSQL → 配置 .env → 运行数据同步 → npm start。
使用流程：通过 Web 界面交互生成地址，或通过 API 程序化调用。
管理：通过管理员控制台监控数据同步状态和管理 API 访问权限。