企业官网建设流程全解析

简介：面向 API 服务运营与开发者的全新二开版接口管理系统源码，基于 Nginx+PHP7.4+MySQL5.7 环境测试运行，访问域名即可完成安装；项目重点修复原版 API 鉴权漏洞与源代码暴露风险，并升级为现代化响应式前后端设计，适配 PC 与移动多终端管理场景，帮助使用者搭建安全、易用的接口管理后台。资源包共 446 个文件，以 zip 压缩包形式提供；主要文件包括 84 个 PHP 后台逻辑与接口文件、217 个 JavaScript 交互脚本、48 个 CSS 样式表，另附 SQL 数据库、字体及图标资源，整体约 20.17MB，目前已有 145 人学习。二开内容覆盖完整：新增 API 分类功能，实现结构化接口管理；API 详情页集成在线调试工具，已登录用户自动获取密钥；后台提供 QPS 限速开关，为后续流量控制预留扩展；同时修复了邮件标题显示问题，并美化支付成功页与通知邮件。整套源码目录规范、前端组件选择成熟，既适合开发者深入研读接口平台设计思路，也可快速二次开发，构建自有 API 计费管理系统。

1. 全新二开版API管理系统源码，为什么卡住大家的总是计费而不是转发

做过API平台的人都有个体会：把一个接口开放出去很简单，但让它按调用量收钱，难度会直接跳到另一个量级。标题里这三个词——二开版、API计费、全开源——其实对应三件事：一套能对外售卖API能力的业务系统、一套能算清账的计量链路、以及一套可以随意改动的完整代码。这类源码的真正价值从不在网关转发那一层，而在计费闭环：谁调了多少次、余额扣到哪、套餐怎么算、密钥怎么发、对账怎么对。这篇文章要聊清楚的就是这件事，读者是手上有API服务想对外变现的团队，或者需要把API能力分发出去、向内部部门摊派调用成本的技术负责人。

2. 二开版API管理系统源码的架构与部署：先用三条线拆清源码再启动

2.1 拆源码的三条业务线：管理后台、API网关、计费Worker

二开版API管理系统源码拿到手，第一件事不是急着配环境，而是把代码按业务线拆开。常见做法是分成管理后台、API网关、计费服务三块，少数实现会把计费直接塞进网关进程里，但那种结构后面对账会很难受。

管理后台负责的是“卖”的动作：创建商户、签发密钥、配置套餐、查看调用报表。API网关负责“转发”的动作：校验签名、检查限流、把请求转发到真正的上游服务，再把响应原样返回。计费服务负责“算账”的动作：从Redis里实时扣减余额、把流水异步落进MySQL、触发余额不足回调。三条线的关系是请求先进网关，网关在转发前调用计费检查，转发完成后计费Worker异步写流水，管理后台只读库和缓存，不参与在线链路。

拆清楚这条线之后，碰到问题就知道该看哪个进程的日志。比如调用方报“余额扣了但请求失败”，问题大概率不在网关，而在计费Worker的补偿逻辑，或者转发之后没有把失败状态传回计费模块。

2.2 本地跑通最小部署：从环境依赖到三个进程同时拉起来

假设这套二开版源码是Python（FastAPI）+ MySQL + Redis 的技术栈，这是目前这类系统里很常见的一种选型，下面以它为例讲部署。环境要求是 Python 3.10+、MySQL 8.0、Redis 6.x，内存至少预留 1GB 给Redis存计费状态。

# 1. 创建虚拟环境并安装依赖，requirements.txt 由源码包自带 python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 2. 复制环境配置模板，改成你自己的连接信息 cp .env.example .env # 编辑 .env：DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、REDIS_HOST、REDIS_PORT # 这三个参数必改：DB_PASSWORD、ADMIN_PASSWORD、SECRET_KEY # 3. 初始化数据库表结构，执行后 MySQL 里会生成 merchant/app_key/plan/billing_log 等表 python scripts/init_db.py # 4. 启动三个进程：管理后台监听 8000，API网关监听 9000，计费Worker常驻后台 uvicorn admin.app:app --host 0.0.0.0 --port 8000 & uvicorn gateway.app:app --host 0.0.0.0 --port 9000 & python worker/billing_worker.py &

第一步和第二步决定了后面所有账能不能算对。DB_PASSWORD 和 SECRET_KEY 必须改，SECRET_KEY 会参与回调通知的签名生成，如果沿用源码包里的默认值，下游调用方拿到源码就能伪造回调。Admin 后台监听 8000 端口，网关监听 9000 端口，两者物理隔离是为了后续给网关单独做水平扩容，计费Worker独立进程则是为了避免在线请求阻塞时扣费延迟。

启动完三个进程后，先确认 Redis 里能读到套餐缓存、MySQL 里能看到四张业务表，再进下一步初始化数据。这里最容易翻车的地方是 MySQL 字符集没设成 utf8mb4，导致下游传 emoji 进去时直接 500，我一般会在 init_db.py 里强制指定DEFAULT CHARSET=utf8mb4。

2.3 初始化最小业务数据：一个商户、一把密钥、一个按次套餐

部署跑通之后，离第一笔计费还差最关键的一步：数据初始化。二开版源码一般会自带初始化脚本，但如果脚本只建表不造业务数据，你就得手动插入。下面是一套最精简的初始化SQL，覆盖商户、密钥、套餐、流水四张核心表，这也是计费链路能跑通的最少数据。

-- 商户：假设这是你的第一个客户 INSERT INTO merchant (name, status) VALUES ('测试商户', 1); -- 套餐：按次计费，每次 0.01 元，余额 10000 次，每分钟限 120 次 INSERT INTO plan (name, price, quota, rate_limit, window_sec) VALUES ('按次体验包', 0.0100, 10000, 120, 60); -- 密钥：app_id 发给下游，secret 只在服务端保存 INSERT INTO app_key (app_id, secret, merchant_id, plan_id, status) VALUES ('app_test_001', 'sk_live_9f8e7d6c5b4a', 1, 1, 1); -- 流水表本身不需要初始化，但这个自增主键和幂等唯一键很关键 -- request_id 是幂等键，同一条请求扣费两次会直接报错 CREATE TABLE IF NOT EXISTS billing_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, request_id VARCHAR(32) NOT NULL UNIQUE, app_id VARCHAR(32) NOT NULL, cost INT NOT NULL DEFAULT 1, status TINYINT DEFAULT 0, created_at DATETIME(3) );

商户表只存身份信息，计费不看它；套餐表里的 price 是每次调用的单价，quota 是剩余可用次数，rate_limit 参与限流判定；app_key 表把下游调用方和套餐绑定在一起，一个商户可以开多个应用，丢给不同项目用。四张表里最重要的是 billing_log，cost 字段我建议用整数存“分”或“厘”，不要用浮点数，哪怕价格表里写的是 0.0100 元，落账时也要转成 1 分，不然月底对账时浮点误差会让你怀疑人生。

初始化完成后，拿 app_id 和一个任意签名去调网关的健康检查接口，能看到 200 就说明这一整套最小闭环已经跑通，可以进入计费模块的实现细节了。

3. 计费模块的实现逻辑：把API调用量变成余额扣减，需要算清四笔账

3.1 先定计费模型：按次、包周期还是阶梯，决定了表的字段怎么设计

计费模型是整个系统的地基，选错后面全是坑。最常见的三种模型是按次计费、包周期套餐、阶梯计费。按次计费最简单，每次调用扣固定金额，适合刚起步的小商户；包周期是按月/按年买固定额度，超额后拒绝服务或转按次；阶梯计费则是在一个周期内，累计调用量跨过某个阈值后单价自动下降，适合中大型API服务。

二开版源码里这三个模型一般会同时存在。实现上按次计费只需要一个 quota 字段递减；包周期要记录周期开始时间和重置时间；阶梯计费麻烦得多，需要一张独立的累计表，按自然日或自然月汇总调用量。我的建议是先只开放按次和包周期两种，阶梯计费等客户真到了那个量级再二开，否则前期光是统计口径就能耗掉你两周。

3.2 用Redis做实时扣减，用MySQL做最终流水：双写才能既快又稳

计费模块的核心矛盾是“快”和“稳”。一次API调用会在几十毫秒内结束，扣费必须同步完成，用MySQL在在线链路里做行锁扣减，并发一高就死锁；但如果只扣Redis，进程一挂账就丢了。所以常见做法是两层配合：Redis负责实时扣减，MySQL流水负责最终对账。

# billing_middleware.py import uuid import time import redis from fastapi import Request, HTTPException # db=1 单独给计费用，不让业务缓存干扰计费数据 r = redis.Redis(host="127.0.0.1", port=6379, db=1, decode_responses=True) async def check_billing(request: Request): # 下游调用方在请求头里带上平台签发的 app_id app_id = request.headers.get("X-App-Id") if not app_id: raise HTTPException(status_code=401, detail="missing app_id") plan_key = f"plan:{app_id}" # 套餐信息在 Redis 里用 hash 缓存：quota 剩余次数、price_val 单价、rate_limit 限流阈值 # 示例：hset plan:app_test_001 quota 10000 price_val 1 rate_limit 120 quota = int(r.hget(plan_key, "quota") or 0) if quota <= 0: # 402 是 HTTP 里专门表示“余额不足”的语义，比 500 好排查 raise HTTPException(status_code=402, detail="insufficient quota") # 生成请求ID，幂等键，流水表里靠它去重 request_id = uuid.uuid4().hex # 先扣后记：INCRBY 是 Redis 原子操作，不用 Lua 也能防超卖 r.hincrby(plan_key, "quota", -1) # 把扣费动作追加到本应用的临时流水队列，Worker 异步刷 MySQL r.lpush(f"billing:queue:{app_id}", f"{request_id}:{int(time.time())}") # 上游转发成功后，网关把 request_id 一并带到响应头，方便调用方排查 return {"request_id": request_id, "app_id": app_id}

这里有两个关键参数必须解释清楚。db=1是给Redis单独划了一个逻辑库，计费相关的 key 全部放在 db 1，管理后台的缓存和会话放 db 0，这样清理缓存时不会误删计费数据。hincrby加-1是原子操作，两个并发请求同时进来时不会都读到同一个 quota 值，这是避免超卖的基本功。

扣费时机的选择值得多说一句：先扣后记，即先扣余额再转发。如果先转发再扣费，上游响应已经返回了但扣费失败，调用方等于免费调了一次；先扣费后转发虽然可能出现“扣了钱但上游超时”的情况，但这个问题可以在避坑章节里用补偿机制解决，比免费调用可控得多。计费中间件返回的 request_id 还会放在响应头里，调用方工单排查时凭这个ID就能在两分钟内定位到流水。

3.3 余额不足与回调通知：别让调用方糊里糊涂断了服

实时扣减之外，二开版API管理系统还必须有主动通知能力：调用方余额见底时，平台不只返回402，还要主动推一个回调给调用方，让他去充值。回调通知最怕两件事：没推到、重复推。所以回调接口必须支持重试，并且用 request_id 做幂等。

# callback.py import hashlib import hmac import time import requests def send_balance_callback(app_id: str, merchant_callback_url: str, secret: str): # 回调体只有四个字段：app_id、额度剩多少、时间戳、签名 payload = { "app_id": app_id, "quota_left": 0, "timestamp": int(time.time()), } # 签名用 HMAC-SHA256，secret 是 app_key 表里那个，签名防伪造 raw = f"{app_id}&{payload['timestamp']}&{payload['quota_left']}" payload["sign"] = hmac.new( secret.encode(), raw.encode(), hashlib.sha256 ).hexdigest() # 重试 3 次，间隔 5 秒、30 秒、300 秒，不阻塞在线请求 for interval in (5, 30, 300): try: resp = requests.post(merchant_callback_url, json=payload, timeout=10) # 调用方回调接口要返回 HTTP 200 才算成功，否则进入下一次重试 if resp.status_code == 200: return True except requests.RequestException: pass time.sleep(interval) return False

回调带了时间戳，所以调用方收到回调后必须校验时间偏差，超过五分钟直接丢弃。签名算法与网关签名保持一致，调用方可以用同一套验签逻辑处理。回调场景里最容易踩的坑是回调接口地址本身配置错误，二开版里这个地址通常在商户表里，但有些源码包会把它写死在配置文件里，导致所有商户共用一个回调地址，测试时能收到、上线后全部推给了同一家，排查时要先去确认回调地址是商户级别还是平台级别的配置。

4. 网关鉴权与路由转发：签名校验、限流和计费如何联动

4.1 基于HMAC-SHA256的签名校验：app_id公开，secret只在服务端

API管理系统的第一道门是鉴权。平台给每个调用方签发一个 app_id 加 secret，app_id 放在请求头里明文传输，secret 不能出现在请求里，否则抓包的人直接就能伪造调用。所以要做签名：调用方把请求参数、时间戳、随机数一起算一个 HMAC-SHA256 签名，服务端用同样的 secret 重算比对。

# auth.py import hashlib import hmac import time from fastapi import Header, HTTPException def verify_sign( app_id: str = Header(..., alias="X-App-Id"), timestamp: str = Header(..., alias="X-Timestamp"), nonce: str = Header(..., alias="X-Nonce"), sign: str = Header(..., alias="X-Sign"), secret: str = "", ): # 时间窗 300 秒，超过就拒绝。防止旧的合法请求被无限重放 if abs(int(time.time()) - int(timestamp)) > 300: raise HTTPException(status_code=401, detail="timestamp expired") # 拼接顺序必须固定，两端用的规则要一模一样 raw = f"{app_id}&{timestamp}&{nonce}" expect = hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest() # compare_digest 防时序攻击，不能用 == 直接比 if not hmac.compare_digest(expect, sign): raise HTTPException(status_code=401, detail="sign mismatch") # 生产环境里，nonce 要放进 Redis 做去重，同一个 nonce 只能用一次 # 这里省略 Redis 部分，避免与计费中间件抢连接影响性能 return app_id

签名校验里最容易漏的是 nonce 去重。时间戳窗口 300 秒意味着一个合法签名在 5 分钟内都有效，如果不去重，攻击者抓包后能在这 5 分钟内无限重放。常见的做法是把 nonce 写进 Redis 的 set 结构，窗口时间设置为与签名时间窗一致。secret 不落请求不代表可以明文存数据库，二开版里 app_key 表的 secret 字段至少要做哈希处理，我见过不少源码把 secret 以明文存，一旦数据库被拖走全部调用方密钥直接暴露。

4.2 限流不只看QPS：把套餐剩余次数与滑动窗口绑在一起

网关的第二道关卡是限流。传统限流只关心每秒请求数，但在API管理系统里，限流必须和套餐联动：同样的 120 次每分钟，按次计费和包周期套餐的触发条件不一样。二开版常见做法是把套餐表里的 rate_limit 和 window_sec 读出来，作为限流阈值传给网关。

# rate_limit.py import time import redis r = redis.Redis(host="127.0.0.1", port=6379, db=1, decode_responses=True) def sliding_window_check(app_id: str, limit: int = 120, window_sec: int = 60): # 用有序集合存每次调用的时间戳，天然实现滑动窗口 key = f"rate:{app_id}" now = time.time() # 先清掉窗口外的老记录，避免 zset 无限膨胀 r.zremrangebyscore(key, 0, now - window_sec) count = r.zcard(key) if count >= limit: raise PermissionError("rate limited") # 当前请求的时间戳入集合，zadd 的 score 和 member 都用时间戳 r.zadd(key, {str(now): now}) # 窗口结束 60 秒后整把 key 过期，防止死数据占内存 r.expire(key, window_sec + 60) return count + 1

这里不是用 Redis 的 INCR 加过期时间做固定窗口，而是用 zset 做滑动窗口，差别在于固定窗口在窗口切换瞬间会出现 2 倍突发流量。zset 方案每次请求都要执行一次 zremrangebyscore，窗口越大成本越高，所以 window_sec 设定为 60 秒、limit 在 1000 以下时性能没有问题。如果套餐有更高限额，我一般会把限流窗口改成 1 秒粒度加 60 秒聚合计数，两种方案配合而不是只用滑动窗口。

限流与计费的联动体现在顺序上：先做限流检查，再做计费扣减。限流失败不扣费，计费失败不转发。两个中间件用同一个 app_id 做 key，但 key 前缀不同，一个是rate:一个是plan:，避免互相覆盖。

4.3 转发时替换上游密钥：对接大模型API服务的统一出口

网关的最后一步是转发到上游真实API服务。这一步是二开版系统和普通反向代理的关键区别：普通代理只改 URL，API计费系统还要在转发时替换认证信息。下游调用方用的是平台签发的 app_id，而上游服务只认平台自己采购的 key，两个 key 不能混。

# forwarder.py import httpx async def forward_to_upstream(api_config: dict, headers: dict, body: bytes): # api_config 里是上游地址、请求方法、超时、以及平台集中管理的上游key # 常见做法是在管理后台维护一张上游API配置表，对接DeepSeek、智谱这类大模型API服务 async with httpx.AsyncClient(timeout=api_config["timeout"]) as client: resp = await client.request( method=api_config["method"], url=api_config["url"], headers={**headers, "Authorization": f"Bearer {api_config['upstream_key']}"}, content=body, ) # 网关原样返回上游响应，不解析body，这样对下游调用方来说是透明的 return resp.status_code, resp.content

转发层的超时参数必须比网关本身超时短，不然网关等上游、下游等网关，会出现两层超时叠加导致的 504。比如网关整体超时设 15 秒，上游转发超时就要设 13 秒，留 2 秒给签名校验和计费扣减。二开版里上游 key 应该集中放在配置表里，由平台统一采购和续费，不能把上游 key 下发给调用方，否则调用方直接绕过平台调上游，这个系统就变成纯转发工具而不是计费平台了。

5. 二开版源码避坑：部署、鉴权、计费最容易翻车的五个地方

5.1 鉴权与路由方向上常踩的坑：上游key配错、超时重试、时间窗过期

现象一：下游调用方明明拿了合法的 app_id，转发时报llm-deepseek: no api key for provider route "deepseek-official"。原因：二开版把上游 key 放在配置表后，运维把平台自己的上游 key 误配到了下游应用的 app_key 上，网关转发时没有做替换，上游收到的是不存在的 key。解决：转发前确认 api_config 表里 upstream_key 字段有值，并且生产环境不要用 init 脚本里的测试 key。我这个坑实际踩过两次，第一次是以为上游服务的问题，排查了半小时才发现是 key 配错了桶。

现象二：一次请求因为网络抖动超时，调用方重试后账单里出现两条扣费记录。原因：计费中间件在转发前先扣费，超时后客户端重试，网关又走了一遍扣费逻辑，同一个业务请求被扣了两次。这是“先扣后记”方案最典型的副作用。解决：扣费之前先查 billing_log 的 request_id，如果客户端重试时带上了原始 request_id，直接返回第一次的响应不算钱。所以网关的响应头一定要返回 request_id，并且引导调用方在重试时带上这个ID。

现象三：上游返回 400，报this model's maximum context length is 1048576 tokens这类参数超长错误。原因：签名校验成功后请求转发给上游大模型API，但请求体太大或参数超限，上游拒绝了。这个不算计费系统自身缺陷，但会让调用方误以为网关有问题。解决：网关只转发不解析，但可以在管理后台配置“上游错误码白名单”，把这类 400 错误透传给调用方的同时标记为“不扣费”。是否对 4xx 扣费要提前定好规矩，我一般遵循 5xx 不扣、4xx 扣一半、2xx必扣，具体在二开版里用 status 字段区分。

5.2 计费与对账方向上常踩的坑：Redis丢了额度、流水丢尾部、统计口径打架

现象四：调用量远没到套餐上限，却突然全部返回 402 余额不足。原因：Redis 里的 plan: 前缀 key 因为内存淘汰策略被回收了，计费中间件读到的 quota 是 0，直接拒绝服务。二开版源码很多默认使用 Redisallkeys-lru淘汰策略，计费 key 和普通缓存一起竞争内存，一旦内存压力上来最先被淘汰的就是这些长尾 key。解决：给计费 key 单独提一个 Redis 实例，或者至少把淘汰策略改成volatile-lru，并且写一个启动预热脚本，把所有 enabled 状态套餐的 quota 从 MySQL 刷进 Redis。

现象五：计费 Worker 重启后，Redis 流水队列里最后十秒的数据丢了，账单少记了调用量。原因：Worker 用 lpop 从billing:queue:{app_id}取数据，进程在 lpop 之后、写 MySQL 之前崩溃，记录就丢了。解决：把 Redis list 换成 Redis Streams，用 XREADGROUP + XACK 做消费确认，Worker 重启后先 XAUTOCLAIM 捞回未确认消息再继续处理。这个改造大概要花半天，但能避免月底对账时账单少几十万的尴尬。

计费统计口径还有一个长期存在的坑：限流按滑动窗口算，账单按自然日聚合，两边数字永远对不上。原因：60 秒滑动窗口在 23:59:30 到 00:00:30 这个区间内跨了两个自然日，限流统计被切成了两段，而账单按自然日切分后就少计或重计了一部分。解决：在报表里同时标注“按自然日”和“按调用窗口”两种口径，别强行让它们相等；如果客户要求严格对账，把计费周期改成从每日零点开始的固定 60 秒窗口，牺牲一点滑动窗口的平滑性换取对账一致性。这个选择没有绝对正确，关键是要在文档里写清楚。

6. 上线前验证：用并发脚本核对“扣费次数=成功调用次数”，再谈卖API

6.1 200并发压测脚本：计费上限要压出来

上线前一天，至少要做一次并发压测，不是压 QPS，而是压计费一致性。我常用的办法是起 200 个线程同时调同一个接口，然后核对三个数字：成功响应数、Redis 里扣减的额度、MySQL 流水条数。

# perf_check.py import threading import requests URL = "http://127.0.0.1:9000/api/v1/demo" HEADERS = {"X-App-Id": "app_test_001", "X-Sign": "test_sign"} ok = fail = 0 lock = threading.Lock() def call(): global ok, fail try: r = requests.get(URL, headers=HEADERS, timeout=5) with lock: if r.status_code == 200: ok += 1 else: fail += 1 except Exception: with lock: fail += 1 threads = [threading.Thread(target=call) for _ in range(200)] for t in threads: t.start() for t in threads: t.join() print(f"ok={ok} fail={fail}")

跑完这个脚本，如果 ok + fail = 200 但 MySQL 流水条数小于 ok 数，说明计费 Worker 消费存在延迟，等 30 秒再查大概率能追上；如果 Redis 扣减数与 ok 数对不上，说明计费中间件有请求没走到扣费逻辑，这时候要去查是不是限流中间件提前拦截了。

6.2 一键核对脚本：对Redis余额和MySQL流水

压测通过后，再做一次静态核对：把 Redis 里的剩余额度、MySQL 流水总量、初始配额三者放在同一个脚本里对比，对不上就说明“先扣后记”链路里有缺口。

# reconcile.py import redis import pymysql r = redis.Redis(host="127.0.0.1", port=6379, db=1, decode_responses=True) conn = pymysql.connect(host="127.0.0.1", user="root", password="***", database="api_platform") init_quota = 10000 quota_left = int(r.hget("plan:app_test_001", "quota")) with conn.cursor() as cur: cur.execute( "SELECT SUM(cost), COUNT(*) FROM billing_log WHERE app_id=%s AND status=1", ("app_test_001",), ) row = cur.fetchone() consumed = row[0] or 0 print(f"初始配额: {init_quota}") print(f"Redis剩余: {quota_left}") print(f"流水扣费: {consumed}")

这可能是整个系统上线前最有价值的一段脚本，它验证的恰恰是“计费”和“调用量”这两件事是否真的等同。如果 Redis 剩余额度与 init_quota - consumed 不相等，说明存在漏记或多扣的流水，绝不带着这个差异上线。我自己的习惯是核对脚本一直保留，每周跑一次，计费系统最怕的不是没有日志，而是日志和余额各说各话——黑匣子状态比明确报错更让人紧张。

这套系统上线后我也多次调整过量价策略，后来意识到二开版源码和维护者自己的工程习惯同样重要，真正的成本不在部署那两天，而在后续每次新套餐、新客户、上游接口变更时，计费链路能不能跟着改对。希望这篇能帮你在动手前就把账算明白，少踩几个我已经替你踩过的坑。

本文还有配套的精品资源，点击获取