alien_py_cloud/alien_snowflake

Alien Snowflake 主键方案

适用于三台 MySQL 服务器（IP 尾段 251/252/253）的分布式雪花算法实现。

设计要点

• Snowflake 位分配：41-bit 时间戳 | 5-bit 机房 | 5-bit 节点 | 12-bit 序列。
• 时间基准：2024-01-01 00:00:00 UTC（EPOCH_MS=1704067200000）。
• 节点映射：默认将 IP 尾段 251/252/253 映射为 worker_id=1/2/3，可通过环境变量覆盖。
• 线程安全：内部使用锁，确保并发安全；发生时钟回拨时抛出异常。

使用方法

1) 直接取号

from alien_snowflake import next_id

pk = next_id()

2) 在 SQLAlchemy 模型中用作主键默认值

from sqlalchemy import BigInteger
from sqlalchemy.orm import mapped_column, Mapped
from alien_snowflake import next_id
from alien_database.base import Base

class Example(Base):
    __tablename__ = "example"
    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, default=next_id)

3) 自定义机房或映射

from alien_snowflake import SnowflakeGenerator, resolve_worker_id

worker_id = resolve_worker_id()  # 自动根据本机 IP 或环境变量映射
gen = SnowflakeGenerator(datacenter_id=0, worker_id=worker_id)
pk = gen.next_id()

IP 映射规则

• 环境变量优先：SNOWFLAKE_WORKER_IP（可填完整 IP 或尾段，如 192.168.0.251 或 251）。
• 默认映射表（DEFAULT_IP_WORKER_MAP）：
  • 251 → worker_id=1
  • 252 → worker_id=2
  • 253 → worker_id=3
• 若需要调整，请修改 alien_snowflake/generator.py 中的 DEFAULT_IP_WORKER_MAP，或在初始化时传入自定义 ip_worker_map。

部署建议

• 确认三台服务器的 IP 与映射一致，或在启动前设定 SNOWFLAKE_WORKER_IP。
• 保障服务器时间同步（NTP），避免时钟回拨；若检测到回拨将抛出异常终止发号。
• 若需更大规模，可扩展 datacenter_id / worker_id 映射，但需保持各节点唯一性。