GeoIP2-CN: Auto Build and Update Solution

【中文文档点此进入】

Overview

This project provides scripts and configuration files for automatically downloading and building the China mainland IP segment from MaxMind’s official GeoLite2 database. It enables users to generate geolocation data files covering the China region based on their own MaxMind License Key. The project aims to offer trustworthy, transparent, and automatically updated geolocation support for China-specific routing and traffic control in tools such as Surge, Clash, Shadowrocket, and Quantumult X.

Project Background

GeoIP databases are widely used in network security and traffic policy routing to determine IP geolocation and assist with smart routing or access control. Many current projects rely on third-party distribution sources, which introduce potential risks:

• Lack of trust chain: Non-official sources cannot be audited and may be tampered with;
• Poor maintainability: Sources may become unavailable without notice;
• Outdated data: Updates may be delayed or irregular.

To address these issues, this project implements a fully self-controlled update mechanism, ensuring the data source is official from MaxMind, structurally traceable, update-controllable, and logically auditable. It is optimized for use in Surge, Clash, and similar tools.

Project Advantages

• Official Data Source: All data is directly fetched from MaxMind, ensuring trust and security;
• Automated Updates: GitHub Actions pulls the latest data every 3 days to maintain synchronization;
• License Compliance: The project uses GitHub Actions to fetch MaxMind data in accordance with the GeoLite2 EULA. Users are strongly encouraged to apply for their own License Key to ensure legal, secure, and traceable data usage.
• Customizable & Controllable: Users can configure output paths, update frequency, target branches, and other parameters to suit their specific deployment needs.

Automated Updates

This project utilizes GitHub Actions for scheduled updates, pulling the latest database every 3 days. No manual intervention is required.

File Path

Filename	Build Output Path (for reference only)	Example Usage
Country.mmdb	data/Country.mmdb	Used in Surge, Clash, QuantumultX for identifying CN IPs

Configuration Guide

Configure MaxMind License Key (Required)

This project requires access to the official MaxMind GeoLite2 database. To enable automated updates, you must:

1. Register on MaxMind and obtain your GeoLite2 License Key

2. Open your repository: GitHub → Settings → Secrets and variables → Actions

3. Create the following Secrets (names must match exactly):

• MAXMIND_ACCOUNT_ID # Your MaxMind Account ID (Required)
• MAXMIND_LICENSE_KEY # Your MaxMind License Key (Required)

Usage Guide

Copy the file URL → Open Surge → Go to General → GeoIP Database → Remove previous configuration (if any) → Paste the new URL → Update Now → Apply → Done!

⚠️ Important Notes

1. In this project, only manual commits (made by real developers) are signed with a GPG key.

   Automated updates (such as GeoLite2 database updates) are executed via GitHub Actions and do not use GPG signatures. Please verify the committer as github-actions[bot] to consider the commit valid and trustworthy.

   • Manual commits are still GPG-signed to identify the authentic developer
   • We do not recommend storing any GPG private keys on GitHub to prevent key leakage and signature abuse

2. It is recommended to combine China.list (for domains) with GEOIP,CN (for IP ranges) to improve accuracy when matching China-related traffic:

   RULE-SET,https://raw.githubusercontent.com/Thoseyearsbrian/Aegis/main/rules/China.list, DIRECT   # Accurately match domains related to China
   GEOIP,CN,DIRECT                                                                                  # Match mainland China IPs not covered by domain rules
   FINAL,REJECT                                                                                     # Final default reject rule (do not place GEOIP below this)
   

3. Do not use GEOIP rules for countries other than mainland China, as the current database only contains CN IP ranges:

   GEOIP, US, PROXY   # Invalid – No matching records found
   GEOIP, AU, PROXY   # Invalid – No matching records found
   GEOIP, CN, DIRECT  # Valid
   

🔐 Disclaimer

The .mmdb file generated by this project is intended for testing and educational purposes only. It must not be used in any form of commercial activity.

Users are solely responsible for ensuring compliance with the MaxMind GeoLite2 EULA and applicable laws and regulations. This project accepts no legal liability for any use of the data.

This project only provides the logic and scripts for building the database and does not distribute original MaxMind data. Users are strongly advised to apply for their own License Key directly from MaxMind.

This project is intended for developers with a technical background and awareness of licensing requirements.

🏅 License Notice

• The .mmdb file built through this project is for research and educational use only. Please read and comply with the MaxMind EULA. This project assumes no responsibility for your use case.

• This project uses GitHub Actions to automatically pull data from MaxMind. You must register on MaxMind and obtain your own License Key to run the build script or automation legally.

• GeoLite2 data is copyrighted by MaxMind, Inc. and is licensed under the GeoLite2 EULA.

• All scripts and configuration files in this project are licensed under the Apache License 2.0.