Appearance
根据 IP 判断访客时区:跨境客服在线时间、预约时段怎么自动适配(Python 实现)
去年帮一家做跨境 SaaS 的团队看工单,发现一批奇怪的投诉:欧洲客户说「你们的在线客服写着 9 点上班,可我发消息的时候明明是下午两点,没人回」。查了后台,客服确实是北京时间 9 点上线——相当于柏林凌晨 2 点。问题不在排班,在于系统里「今天」和「9 点」这两个概念,从头到尾都是按服务器时区算的。
这类问题在只有中文用户的站里很难被发现,一旦有了海外客户、或者在新疆西藏有用户,就集中爆出来。修复它的第一步,是搞清楚「这个访客现在几点」——而服务端能拿到的信号,通常只有 IP。
一、时间信号有三层,IP 是最后那层
排查过一轮你会发现,能告诉你时区的东西其实有三个:
| 信号 | 准确度 | 什么时候有 |
|---|---|---|
浏览器时区 Intl.DateTimeFormat().resolvedOptions().timeZone | 高(跟随系统设置) | 只有用户开着页面、JS 跑起来时 |
| 用户自己在账号里填的时区/国家 | 最高 | 只有填过的人有,通常不到三成 |
| IP 归属地 | 中(城市级) | 任何一次服务端请求都有 |
所以工程上的顺序是:前端能拿到就用前端的,拿不到用用户设置,都没有才用 IP 兜底。真正离不开 IP 的场景是这些——它们全都没有前端参与:
- 定时任务给客户发日报、账单提醒、续费通知;
- 短信和邮件营销的发送窗口;
- 客服系统在访客一进来就显示「对方当地时间 23:40,可能已休息」;
- 预约系统渲染可选时段;
- 事后分析:一批投诉到底集中在哪个时区的用户。
这篇文章解决的就是这一层。示例用 Python,接口是 IP9 的免费版单 IP 查询。
二、IP 推时区,只能做三层推导
很多人以为 IP 归属地接口会直接返回时区。IP9 不返回,GeoIP 类的库通常也不返回——因为「IP 属于哪个时区」本身没有权威数据,只有「IP 在哪个城市」和「城市在哪个时区」两张表拼出来的近似值。
推导分三层,准确度依次下降:
第一层:国家 → 时区。 对中国、日本、韩国、德国、法国这类单一时间国家,一次映射就够了。中国全境统一 UTC+8,包括新疆和西藏。
第二层:省/州 → 时区。 美国、加拿大、澳大利亚、俄罗斯、巴西、印尼这些国家横跨多个时区,必须细分到州。这里有个现实问题:IP9 的 prov 字段在国内很可靠(省),海外经常是空的。我实测过 8.8.8.8 和 1.1.1.1,返回的国家是「美国」「澳大利亚」,prov 和 city 都是空串。这种情况下你只能退到国家默认时区,美国会被当成纽约时间——对西海岸客户就差了三个小时。
第三层:经度粗算。 拿 lng 除以 15 得到 UTC 偏移。8.8.8.8 的经度是 -97.82(美国地理中心点),算出来 UTC-7,对美国中部勉强能用,对纽约和洛杉矶都是错的。所以这一层只适合判断「对方大概在白天还是半夜」,不要用它去排具体时刻。
中国还有个坑:不能按经度算。 乌鲁木齐经度 87.6,除以 15 是 UTC+5.8,但当地官方时间就是北京时间 UTC+8。真正的差异在作息——新疆的商场上午 10 点开门,夏天晚上 8 点天还亮着。正确处理是保持 Asia/Shanghai 时区,把服务时段整体后移,而不是给新疆算一个 UTC+6。
三、夏令时:写死偏移一定会翻车
见过最典型的一段代码是这样的:
python
offset = 1 if country == "DE" else 8 # 德国 UTC+1,中国 UTC+8这段在夏天会错一个小时。德国 3 月最后一个周日到 10 月最后一个周日是 UTC+2,其余时间 UTC+1;美国是 3 月第二个周日到 11 月第一个周日;南半球的澳大利亚、巴西方向相反;俄罗斯 2014 年之后干脆取消了夏令时。
还有一类更容易被忽略:非整点时区。印度 UTC+5:30,尼泊尔 UTC+5:45,伊朗 UTC+3:30,缅甸 UTC+6:30。用整数小时做偏移,这些国家的用户会看到「半点」的时间,预约时段直接错位。
正确做法是用 IANA 时区数据库(Python 3.9 起标准库自带 zoneinfo),把「时区名」而不是「偏移量」存下来,让库去处理夏令时。代码里唯一要注意的是运行环境:Debian slim 镜像和 Alpine 默认不带 tzdata,zoneinfo 会抛 ZoneInfoNotFoundError,需要 apt install tzdata 或 apk add tzdata。
四、Python 实现
下面这段是完整可跑的:查归属地 → 推时区 → 算当地时间 → 判断是否在服务时段。带缓存、限速重试和失败降级。
python
import time
from datetime import datetime, timedelta, timezone
from functools import lru_cache
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
import requests
API = "https://ip9.com.cn/get"
COUNTRY_TZ = {
"cn": "Asia/Shanghai", "hk": "Asia/Hong_Kong", "mo": "Asia/Macau", "tw": "Asia/Taipei",
"jp": "Asia/Tokyo", "kr": "Asia/Seoul", "sg": "Asia/Singapore", "th": "Asia/Bangkok",
"vn": "Asia/Ho_Chi_Minh", "id": "Asia/Jakarta", "my": "Asia/Kuala_Lumpur",
"ph": "Asia/Manila", "in": "Asia/Kolkata", "ae": "Asia/Dubai", "sa": "Asia/Riyadh",
"gb": "Europe/London", "de": "Europe/Berlin", "fr": "Europe/Paris", "it": "Europe/Rome",
"es": "Europe/Madrid", "nl": "Europe/Amsterdam", "pl": "Europe/Warsaw",
"ru": "Europe/Moscow", "tr": "Europe/Istanbul", "eg": "Africa/Cairo",
"za": "Africa/Johannesburg", "ng": "Africa/Lagos", "br": "America/Sao_Paulo",
"ar": "America/Argentina/Buenos_Aires", "mx": "America/Mexico_City",
"cl": "America/Santiago", "co": "America/Bogota",
"us": "America/New_York", "ca": "America/Toronto",
"au": "Australia/Sydney", "nz": "Pacific/Auckland",
}
# 多时区国家按省/州细化;键用接口返回的 prov 小写,生产环境要维护完整表
REGION_TZ = {
("us", "加利福尼亚"): "America/Los_Angeles",
("us", "华盛顿"): "America/Los_Angeles",
("us", "德克萨斯"): "America/Chicago",
("us", "伊利诺伊"): "America/Chicago",
("us", "纽约"): "America/New_York",
("ca", "不列颠哥伦比亚"): "America/Vancouver",
("ca", "安大略"): "America/Toronto",
("au", "西澳大利亚"): "Australia/Perth",
("au", "昆士兰"): "Australia/Brisbane",
("ru", "新西伯利亚"): "Asia/Novosibirsk",
("ru", "伊尔库茨克"): "Asia/Irkutsk",
("br", "亚马孙"): "America/Manaus",
}
SERVICE_HOURS = {"cn": (9, 21), "jp": (9, 18), "kr": (9, 18), "de": (8, 18),
"gb": (8, 18), "us": (8, 20), "au": (9, 17), "default": (9, 18)}
REST_SHIFT = {"新疆": 2, "西藏": 1, "青海": 1} # 当地作息比北京时间晚几小时
def query_geo(ip: str, timeout: float = 2.0) -> dict | None:
"""调 IP9 单 IP 接口,返回 data 字典;非法 IP 或彻底失败返回 None。"""
last_err = "unknown"
for attempt in range(3):
try:
resp = requests.get(API, params={"ip": ip}, timeout=timeout)
except requests.RequestException as exc:
last_err = type(exc).__name__
time.sleep(0.2 * (attempt + 1))
continue
if resp.status_code == 429: # 免费版 60 次/分钟,超了等一秒再试
last_err = "rate limited"
time.sleep(1.0)
continue
if resp.status_code != 200:
last_err = f"http {resp.status_code}"
break
payload = resp.json()
if payload.get("ret") != 200: # 400 = IP 非法,重试没意义
return None
return payload["data"]
print(f"[warn] {ip} 查不到:{last_err}")
return None
@lru_cache(maxsize=50000)
def profile(ip: str) -> dict:
"""归属地 -> 时区 + 服务时段。同一 IP 一天只查一次。"""
geo = query_geo(ip)
if not geo:
return {"tz_name": "UTC", "tz": timezone.utc, "confidence": "fallback",
"country": "", "prov": "", "city": "", "window": SERVICE_HOURS["default"]}
cc = (geo.get("country_code") or "").lower()
prov = geo.get("prov") or ""
tz_name = REGION_TZ.get((cc, prov.lower())) or COUNTRY_TZ.get(cc)
confidence = "region" if (cc, prov.lower()) in REGION_TZ else "country"
if tz_name:
try:
tz = ZoneInfo(tz_name)
except ZoneInfoNotFoundError: # 系统缺 tzdata 时降级,不要让请求挂掉
tz, tz_name, confidence = timezone.utc, "UTC", "fallback"
else:
# 没有国家映射才用经度粗算,只能判断白天/半夜
offset = max(-12, min(14, round(float(geo.get("lng") or 0) / 15)))
tz = timezone(timedelta(hours=offset))
tz_name, confidence = f"UTC{offset:+d}", "longitude"
start, end = SERVICE_HOURS.get(cc, SERVICE_HOURS["default"])
shift = REST_SHIFT.get(prov, 0) if cc == "cn" else 0
return {"tz_name": tz_name, "tz": tz, "confidence": confidence,
"country": geo.get("country"), "prov": prov, "city": geo.get("city") or "",
"window": (start + shift, end + shift)}
def visitor_status(ip: str, now: datetime | None = None) -> dict:
p = profile(ip)
local = (now or datetime.now(timezone.utc)).astimezone(p["tz"])
start, end = p["window"]
return {
"ip": ip,
"where": " ".join(x for x in (p["country"], p["prov"], p["city"]) if x),
"tz": p["tz_name"],
"local_time": local.strftime("%Y-%m-%d %H:%M"),
"utc_offset": local.strftime("%z"),
"in_service": start <= local.hour + local.minute / 60 < end,
"window": f"{start:02d}:00-{end:02d}:00",
"confidence": p["confidence"],
}
if __name__ == "__main__":
for ip in ["114.114.114.114", "8.8.8.8", "85.214.132.117", "210.140.92.183"]:
print(visitor_status(ip))我这边跑出来是这样(confidence=country 表示只到国家层,in_service 按 9-21 点算):
{'ip': '114.114.114.114', 'where': '中国 江苏 南京', 'tz': 'Asia/Shanghai', 'local_time': '2026-11-09 07:05', 'utc_offset': '+0800', 'in_service': False, 'confidence': 'country'}
{'ip': '8.8.8.8', 'where': '美国', 'tz': 'America/New_York', 'local_time': '2026-11-08 18:05', 'utc_offset': '-0500', 'in_service': True, 'confidence': 'country'}
{'ip': '85.214.132.117', 'where': '德国 柏林 柏林', 'tz': 'Europe/Berlin', 'local_time': '2026-11-09 00:05', 'utc_offset': '+0100', 'in_service': False, 'confidence': 'country'}注意第二行:11 月 8 日纽约的偏移已经是 -0500,说明夏令时已经结束。如果代码里把美国写死成 -0400,这一天的客服排班就会整体错一小时——这类 bug 一年只出现两次,但每次都很难查。
profile() 上的 lru_cache 是性能关键。IP 归属地不会分钟级变化,一个 IP 缓一天完全够用;免费版 60 次/分钟的限制,配上缓存之后,日活几千的小站基本碰不到上限。真要重启后还保留缓存,把 profile 换成一层 Redis 读写,key 用 IP、TTL 设 86400 就行。
五、落地时最容易踩的五个点
1. 拿到的 IP 可能是 CDN 的。 挂在 Cloudflare 或国内 CDN 后面,request.remote_addr 是边缘节点地址,归属地会变成节点所在城市。取 X-Forwarded-For 的第一段,并且只信任自己 CDN 的网段——否则这个头用户能随便伪造。
2. 代理和 VPN 会让时区偏。 客户连公司 VPN 访问你的站,IP 是 VPN 出口,时区自然跟着出口走。客服系统里要留一个「手动纠正」的入口,别把它做成只读展示。
3. 计费日切别用访客时区。 账单周期、用量统计这类东西必须用固定时区(UTC 或公司注册地时区)。按访客时区算的话,夏令时切换那天会出现 23 小时或 25 小时,按小时计费的产品必然漏计或重复计。
4. 预约时间存 UTC + 时区名,不要存本地字符串。 2026-11-20 10:00 Europe/Berlin 是安全的,2026-11-20 10:00 一旦用户改时区就废了。
5. 合规上只留到城市级。 时区、城市、国家足够支撑排班和统计,完整 IP 不必长期留存。日志里做「留地域、去 IP」的脱敏,既满足分析需求,也少一堆隐私风险。
总结
落地顺序建议这样:前端先接浏览器时区,账号体系里补一个可选的时区字段,服务端用 IP 兜底并标注可信度。三层都有的时候,按「用户设置 > 浏览器 > IP」取,冲突时记一条日志,跑一个月你就能看到自己用户的实际分布,再回头调服务时段。
IP9 的免费接口就是 https://ip9.com.cn/get?ip=<ip>(不传 ip 查当前请求方),返回 country、country_code、prov、city、isp、lng、lat(城市中心点)、big_area 这些字段,IPv4 和 IPv6 都支持。海外场景如果只到国家层不够用,VIP 版才有区县和 ip_type,按次计费,具体口径看官网 https://www.ip9.com.cn 的说明。时区这件事没有「一次接对」的解法,先让 confidence 可见,再逐步补表,比追求一步到位靠谱。