backend: 交付网站后端 + 本地自助管理后台 + 测试工程(已脱敏)

Browse Source
范围由店主圈定:网页后端 / 自助后端、本地的自助管理后台、
用于测试的 Blender 工程、以及部署层的反代片段。

出站纪律:所有指向真实环境的值(域名/端口/盘符路径/IP/账户名)已替换为占位;
代码里本来就没有硬编码凭据(令牌走文件与环境变量)。
Blender 工程因内嵌绝对路径,做了等长替换(文件字节数未变,结构完好)。

两份交接文档各含《我们的思路与方法》,并要求对方回:
问题分析 + 改正意见 + 他改了什么(含是否动到接口/字段/数据格式)。
This commit is contained in:
Suda
2026-10-05 18:52:33 +08:00
parent 1903daafc3
commit 1d67fda9d5
30 changed files with 8486 additions and 0 deletions
+537
View File
@@ -0,0 +1,537 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
金钻工坊 · 渲染下单 —— 管理工具(**只在本机跑**,不开公网入口)
python3 admin.py gen 50 --batch 2026-09-30 --value 6 批量生成 50 个码(导出 CSV)
python3 admin.py gen 1 --tpl wheat --n-fix 3 张数卡密:这张码只能出 3 张
python3 admin.py edit <卡密> --n-fix 5 / --unlimited / --lock-tpl / --off
改一张还没用掉的卡密(张数/锁模板/停用)
python3 admin.py codes [--used|--unused] 看码库
python3 admin.py ls [waiting|working|done|failed] 看订单
python3 admin.py show <订单号> 看单详情
python3 admin.py retry <订单号> 把单子退回队列重渲
python3 admin.py calls 看「呼叫金钻」记录
python3 admin.py sweep 清理超过保留期的成品
python3 admin.py stat 概览
python3 admin.py audit [行数] 看兑换码失败/被拒记录
"""
import csv, json, os, shutil, sys, time
from datetime import datetime, timedelta
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import server as S # noqa: E402
def cmd_gen(argv):
# ⚠️ 2026-10-01 实踩:`gen --help` 会被当成普通参数 → **直接生成 10 张真码**。
# 管理工具绝不能"看个帮助就产生副作用"。
if any(a in ("-h", "--help") for a in argv):
print("""gen 用法:
gen 50 生成 50 张(一张码一张图)
gen 20 --platform 爱发电 打平台标记(买家填码时会显示来源并预选模板)
gen 20 --n-fix 1 固定张数:这张码只能出 1 张
gen 5 --n-free 不限张数
gen 20 --unlimited --direct 不限张数 + 直发(不用确认收货,直接给原图)
gen 10 --tpl wheat 预选模板(买家填码自动勾上)
gen 20 --platform 爱发电 --n-fix 1 --export payplatform.txt
★ 顺手导出「一行一码」纯文本,直接贴进爱发电的自动发货卡池""")
return 0
n = int(argv[0]) if argv and argv[0].isdigit() else 10
batch, value, platform, tpl, is_set, direct = "", 6, "", "", False, False
n_fix, n_max, lock_tpl, n_free, export = 0, 0, False, False, ""
for i, a in enumerate(argv):
if a == "--batch" and i + 1 < len(argv):
batch = argv[i + 1]
if a == "--value" and i + 1 < len(argv):
value = argv[i + 1]
# 第三方平台的标记:闲鱼 / B站工坊 …(金钻 2026-09-30)
# 买家填码时页面会显示「来自闲鱼 · 麦田萤火」并自动预选模板,不用他自己挑
if a == "--platform" and i + 1 < len(argv):
platform = argv[i + 1]
# --export 文件名:导出一份「一行一码」的纯文本。
# 金钻 2026-10-01(P4):爱发电的「自动发货」= 你填一池子卡密,买家付款它自己发一张。
# 这里直接产出能整段粘进去的文本,省掉手工挑码。
if a in ("--export", "--dlv") and i + 1 < len(argv):
export = argv[i + 1]
if a == "--tpl" and i + 1 < len(argv):
tpl = argv[i + 1]
# --set = 套装卡密:一张码管一整套(全部皮肤 × 全部模板)
if a == "--set":
is_set = True
# --direct = 金钻自己发的码(个人收款卖的):不用等确认收货,看完预览直接下
if a == "--direct":
direct = True
# 张数卡密(金钻 2026-09-30 晚):
# --n-fix 3 → 这张码**只能出 3 张**(模板随便改,张数不能多也不能少)
# --n-max 10 → 最多 10 张(不限张数也可以封个顶)
# --lock-tpl → 码里带的模板锁死,买家不能改
if a in ("--n-fix", "--n-max") and i + 1 < len(argv):
try:
if a == "--n-fix":
n_fix = int(argv[i + 1])
else:
n_max = int(argv[i + 1])
except ValueError:
print("❌ %s 要跟一个整数" % a)
return
if a == "--lock-tpl":
lock_tpl = True
# --unlimited → 不限张数(买家想出几张出几张;老规矩「一张码一张图」也解除)
if a == "--unlimited":
n_free = True
# --tpl 支持逗号分隔多个(套装卡密:一张码预选一组模板)
tpl_list = [x.strip() for x in tpl.split(",") if x.strip()]
bad = [x for x in tpl_list if x not in S.TPL_KEYS]
if bad:
print("❌ 模板 key 不认识:%s\n 可选:%s" % (",".join(bad), " / ".join(S.TPL_KEYS)))
return
tpl = ",".join(tpl_list)
if lock_tpl and not tpl:
print("❌ --lock-tpl 要跟 --tpl 一起用(没有模板,锁什么?)")
return
if n_free and n_fix:
print("❌「不限张数」和「固定张数」只能选一个")
return
made = S.gen_codes(n, batch, value, platform, tpl, is_set=is_set, direct=direct,
n_fix=n_fix, n_max=n_max, lock_tpl=lock_tpl, n_free=n_free)
stamp = S.now().strftime("%Y%m%d-%H%M%S")
out = os.path.join(S.ROOT, "exports", "codes-%s.csv" % stamp)
os.makedirs(os.path.dirname(out), exist_ok=True)
# ⚠️ 同一秒连开两批会撞名互相覆盖(2026-09-30 实踩)→ 撞了就在后面加 -2/-3
n_dup = 1
while os.path.exists(out):
n_dup += 1
out = os.path.join(S.ROOT, "exports", "codes-%s-%d.csv" % (stamp, n_dup))
with open(out, "w", newline="", encoding="utf-8-sig") as f:
w = csv.writer(f)
w.writerow(["兑换码", "面额", "批次", "平台", "模板", "固定张数", "不限张数",
"最多张数", "锁定模板"])
for c in made:
w.writerow([c, value, batch, platform, tpl, n_fix or "",
"是" if n_free else "", n_max or "", "是" if lock_tpl else ""])
print("已生成 %d 个兑换码(面额 ¥%s,批次 %s,平台 %s,模板 %s%s%s%s%s)"
% (len(made), value, batch or "-", platform or "-", tpl or "-",
",★套装(一张管一整套)" if is_set else "",
",◆直发(不用等收货)" if direct else "",
(",张数固定 %d 张" % n_fix) if n_fix
else ((",不限张数" if n_free else ",最多 %d 张" % n_max) if (n_free or n_max) else ",一张码一张图"),
",🔒模板锁定不能改" if lock_tpl else ""))
for c in made:
print(" " + c)
print("\nCSV: %s" % out)
# ---- 发卡文本(金钻 2026-10-01 P4:爱发电/闲鱼「自动发货」直接整段粘)----
if export:
ex_dir = os.path.join(S.ROOT, "exports")
os.makedirs(ex_dir, exist_ok=True)
p = export if os.path.isabs(export) else os.path.join(ex_dir, export)
with open(p, "w", encoding="utf-8") as f:
f.write("\n".join(made) + "\n")
os.chmod(p, 0o640)
print("""
发卡文本: %s (%d 行,一行一码,可直接整段粘贴)
▸ 爱发电:创作中心 → 商品 → 编辑 → 发货方式「自动发货」→ 把那几行粘进去 → 保存
买家付款后爱发电自动发一张给他,他到 shop.example.com/order/ 点「卡密下单」填码就行
▸ 闲鱼/B站工坊:发货时复制一行发给买家
⚠️ 这份文本等于钱,别发群里、别进公开仓库(已设 640 权限)""" % (p, len(made)))
return 0
def cmd_codes(argv):
codes = S.load_codes()
flt = argv[0] if argv else ""
for c, v in sorted(codes.items()):
if flt == "--used" and not v.get("used"):
continue
if flt == "--unused" and v.get("used"):
continue
q = ("固定 %d 张" % v["n_fix"]) if v.get("n_fix") else \
("不限张数" if v.get("n_free") else (("最多 %d 张" % v["n_max"]) if v.get("n_max") else "1 码 1 张"))
stt = {"active": "可用", "bound": "已激活", "used": "已核销",
"inactive": "停用"}.get(S.code_state(v), "?")
tags = "%s%s%s%s" % (
("【%s】" % v["platform"]) if v.get("platform") else "",
("【%s】" % v["tpl"]) if v.get("tpl") else "",
"🔒" if v.get("lock_tpl") else "",
"◆直发" if v.get("direct") else "")
print("%s %-6s 张数=%-8s %s 订单=%s %s" % (
c, stt, q, tags, v.get("order") or "-",
v.get("ts") or v.get("bound_at") or ""))
stc = [S.code_state(v) for v in codes.values()]
print("\n合计 %d 张:可用 %d / 已激活 %d / 已核销 %d / 停用 %d"
% (len(codes), stc.count("active"), stc.count("bound"),
stc.count("used"), stc.count("inactive")))
def cmd_edit(argv):
"""改一张还没用掉的卡密(张数 / 锁定模板 / 直发 / 停用…)。
金钻 2026-09-30 晚:「这个也给你开 api,方便我管理和你介入」
用法:
admin.py edit <卡密> --n-fix 5 固定出 5 张(不能多也不能少)
admin.py edit <卡密> --unlimited 改成不限张数
admin.py edit <卡密> --n-max 20 封顶 20 张
admin.py edit <卡密> --lock-tpl 模板锁死(要码里已有模板)
admin.py edit <卡密> --unlock-tpl 解锁模板
admin.py edit <卡密> --tpl wheat,sakura 换一组模板
admin.py edit <卡密> --off / --on 停用 / 启用
"""
if not argv:
print(cmd_edit.__doc__)
return
code, p = argv[0], {}
for i, a in enumerate(argv):
nxt = argv[i + 1] if i + 1 < len(argv) else None
if a == "--n-fix" and nxt:
p["n_fix"] = nxt
elif a == "--n-max" and nxt:
p["n_max"] = nxt
elif a == "--unlimited":
p["unlimited"] = True
elif a == "--tpl" and nxt:
p["tpls"] = [x.strip() for x in nxt.split(",") if x.strip()]
elif a == "--lock-tpl":
p["lock_tpl"] = True
elif a == "--unlock-tpl":
p["lock_tpl"] = False
elif a == "--direct":
p["direct"] = True
elif a == "--no-direct":
p["direct"] = False
elif a == "--set":
p["set"] = True
elif a == "--no-set":
p["set"] = False
elif a == "--off":
p["state"] = "inactive"
elif a == "--on":
p["state"] = "active"
elif a == "--platform" and nxt:
p["platform"] = nxt
if not p:
print("没给要改什么 —— 看用法:")
print(cmd_edit.__doc__)
return
ok, e, info = S.edit_code(code, p)
if not ok:
print("❌ " + e)
return
print("✅ %s 改好了:张数 %s | 模板 %s%s | 直发 %s | 状态 %s"
% (info["code"],
(("固定 %d 张" % info["n_fix"]) if info["n_fix"]
else (("最多 %d 张" % info["n_max"]) if info["n_max"] else "不限")),
",".join(info["tpls"]) or "自由选",
"(🔒锁定)" if info["lock_tpl"] else "",
"是" if info["direct"] else "否", info["state"]))
def cmd_ls(argv):
st = argv[0] if argv else None
rows = S.list_orders((st,) if st else None)
if not rows:
print("(没有订单)")
return
for m in sorted(rows, key=lambda x: x.get("created") or ""):
print("%-10s %-8s %-19s %d 张 %s %s" % (
m["oid"], m.get("state"), m.get("created", ""),
len(m.get("templates") or []), m.get("arm"),
",".join(m.get("templates") or [])))
print("\n共 %d 单" % len(rows))
def cmd_show(argv):
if not argv:
sys.exit("用法: admin.py show <订单号>")
m = S.read_meta(argv[0])
if not m:
sys.exit("没有这个订单")
m2 = dict(m)
m2.pop("token", None)
print(json.dumps(m2, ensure_ascii=False, indent=1))
def cmd_retry(argv):
if not argv:
sys.exit("用法: admin.py retry <订单号>")
oid = argv[0]
m = S.read_meta(oid)
if not m:
sys.exit("没有这个订单")
m["state"] = "waiting"
m["note"] = "管理员退回重渲"
m["started"] = m["finished"] = None
S.write_meta(oid, m)
print("%s 已退回队列" % oid)
def cmd_calls(argv):
try:
for line in open(S.CALLS_FILE, encoding="utf-8"):
if line.strip():
r = json.loads(line)
print("%s 订单=%s IP=%s %s" % (r["ts"], r.get("order") or "-",
r.get("ip"), "已通知" if r.get("notified") else "未通知"))
except OSError:
print("(没有呼叫记录)")
def cmd_sweep(argv):
"""清过期成品 + **核销卡密**(金钻 2026-09-30 晚:「核销要等开放下载后 72 小时」)。
到期口径改用 S.expire_at():确认收货/直发出图之后 72 小时(没开放下载的用创建时间兜底)。
⚠️ 删文件之前先把卡密核销 —— 否则文件没了、码还挂在「已激活」,账永远对不上。
"""
n = freed = settled = 0
for oid in list(os.listdir(S.ORDERS)):
d = os.path.join(S.ORDERS, oid)
m = S.read_meta(oid)
if not m:
continue
exp = S.expire_at(m)
if exp is None or exp > datetime.now(S.CST):
continue
settled += S.settle_codes(oid, "订单到期清理(开放下载满 %dh)" % S.KEEP_HOURS)
for root, _, files in os.walk(d):
for f in files:
try:
freed += os.path.getsize(os.path.join(root, f))
except OSError:
pass
shutil.rmtree(d, ignore_errors=True)
n += 1
# 文件还在、但开放下载已满 72 小时的,也一起核销
settled += sum(x[1] for x in S.settle_due())
print("清理 %d 单,释放 %.1f MB,核销卡密 %d 张" % (n, freed / 1048576, settled))
def cmd_audit(argv):
n = int(argv[0]) if argv and argv[0].isdigit() else 40
try:
lines = [l for l in open(S.LOG_FILE, encoding="utf-8").read().splitlines()
if ("兑换码失败" in l or "拒绝" in l)]
except OSError:
lines = []
for l in lines[-n:]:
print(l)
print("\n共 %d 条异常记录" % len(lines))
def cmd_activate(argv):
"""网页下单:买家付了款,激活这一单 → 进队列开渲。"""
oid = (argv[0] if argv else "").strip().upper()
if not oid:
print("用法: activate <订单号>")
return
m = S.read_meta(oid)
if not m:
print("没有这个订单:%s" % oid)
return
st = m.get("state")
if st not in ("unpaid", "paid"):
print("订单 %s 现在是「%s」,不是待付款,没动它" % (oid, st))
return
m["state"] = "waiting"
m["paid_at"] = S.now().isoformat(timespec="seconds")
with S.LOCK:
S.write_meta(oid, m)
print("✅ 订单 %s 已激活 → 进入排队" % oid)
print(" 模板:%s | 分辨率:%s | 码:%s"
% (",".join(m.get("templates") or []), m.get("res"), ",".join(m.get("codes") or [])))
def cmd_pending(argv):
"""列出待付款的网页单(等你收钱激活的)"""
rows = S.list_orders(("unpaid", "paid"))
if not rows:
print("没有待付款 / 待激活的网页单")
return
for m in rows:
tag = "★买家已报付款" if m.get("state") == "paid" else "还没付款"
print("%s %-12s ¥%-5s %s 张 %s 码 %s"
% (m["oid"], tag, m.get("amount") or (S.PRICE_UNIT * len(m.get("templates") or [] or [1])),
len(m.get("templates") or []), ",".join(m.get("templates") or []),
",".join(m.get("codes") or [])))
print("\n共 %d 单 —— 确认到账后跑:python3 admin.py activate <订单号>" % len(rows))
def cmd_stat(argv):
codes = S.load_codes()
st = [S.code_state(v) for v in codes.values()]
print("卡密 %d 张(可用 %d / 已激活 %d / 已核销 %d / 停用 %d)"
% (len(codes), st.count("active"), st.count("bound"),
st.count("used"), st.count("inactive")))
hb = S.heartbeat()
print("渲染机 %s 最后心跳 %s" % ("在线" if hb["online"] else "离线", hb["last_seen"]))
for st in ("unpaid", "paid", "waiting", "working", "done", "failed"):
print("订单 %-8s %d" % (st, len(S.list_orders((st,)))))
total = 0
for root, _, files in os.walk(S.ROOT):
for f in files:
try:
total += os.path.getsize(os.path.join(root, f))
except OSError:
pass
print("数据占用 %.1f MB" % (total / 1048576))
def cmd_price(argv):
"""价格档位(金钻 2026-10-01:「按张数和优惠设置专属购买价格链接」)
看: python3 admin.py price
设: python3 admin.py price set 3 15 http<WIN-PATH>
(第 3 档 = 买 3 张 ¥15,付款按钮就跳这个商品链接;链接可省 = 用总链接)
删: python3 admin.py price rm 3
单价: python3 admin.py price per 6 (没配档位的张数按这个算)
"""
d = S.price_tiers()
tiers = d.get("tiers") or {}
if not argv:
print("单价(没配档位时):¥%g/张" % d["per"])
print("%-6s %-8s %s" % ("张数", "价格", "专属商品链接"))
for k in sorted(tiers, key=lambda x: int(x) if x.isdigit() else 99):
t = tiers[k] or {}
print("%-6s ¥%-7s %s" % (k, t.get("price"), t.get("payplatform") or "(用总链接)"))
if not tiers:
print("(还没配任何档位)")
print("\n设一档:python3 admin.py price set 3 15 http<WIN-PATH>")
return
sub = argv[0]
if sub == "per" and len(argv) > 1:
d["per"] = float(argv[1])
elif sub == "set" and len(argv) > 2:
n, price = argv[1], argv[2]
if not n.isdigit() or int(n) < 1:
raise SystemExit("张数要正整数")
tiers[n] = {"price": float(price), "payplatform": (argv[3] if len(argv) > 3 else "").strip()}
elif sub == "rm" and len(argv) > 1:
tiers.pop(argv[1], None)
else:
raise SystemExit("用法:price / price per N / price set N 价格 [链接] / price rm N")
d["tiers"] = tiers
S.jsave(S.PRICES_FILE, d)
try:
os.chmod(S.PRICES_FILE, 0o644)
except OSError:
pass
print("改好了 —— 现在:")
cmd_price([])
def cmd_gift(argv):
"""福利券(金钻 2026-10-01「赛博鸡蛋」):一批**免费、免付费、只限张数**的码,买家自取。
看: python3 admin.py gift
开一批:python3 admin.py gift new 赛博鸡蛋 --count 50 --n-fix 1
加 --tpl sakura --lock → 只让领的人试这个新模板(试玩券)
加 --days 7 → 7 天后自动收摊
加 --no-direct → 领到的券也要走「确认收货」才给原图(默认直发)
补货:python3 admin.py gift add <批次id> --count 20
收摊:python3 admin.py gift off <批次id> (已领到手的券不受影响)
⚠️ 建/补/收的逻辑全在 server.py(gift_batch_new / gift_batch_add / gift_batch_off)——
金钻电脑上那块**面板**(ys_admin.py 的「免费码」区块)调的是同一批函数。
**改规则只改 server.py 那一处**,别在这儿再写一遍(两边必漂移)。
"""
def show_all():
rows = S.gift_batches()["batches"] # 每次现读:刚建/补完的批次要立刻看见
if not rows:
print("(还没有福利券批次)")
return
print("%-16s %-16s %-6s %-6s %-8s %s" % ("批次", "名字", "总数", "已领", "还剩", "限制"))
for b in rows:
st = S.gift_stat(b["id"])
lim = "%d 张/人" % int(b.get("each") or 1)
lim += ",锁模板 %s" % b["tpl"] if b.get("lock_tpl") else ""
lim += ",%s 到期" % b["expire"] if b.get("expire") else ""
if not b.get("enabled", True):
lim += "(已收摊)"
print("%-16s %-16s %-6d %-6d %-8d %s"
% (b["id"], b.get("name") or "", st["total"], st["claimed"], st["left"], lim))
if not argv:
show_all()
return
sub = argv[0]
if sub == "new" and len(argv) > 1:
name = argv[1]
op = {"count": 20, "n-fix": 1, "each": 1, "tpl": "", "lock": False,
"days": 0, "note": "", "direct": True, "kind": "render", "free": False}
i = 2
while i < len(argv):
a = argv[i]
if a == "--count" and i + 1 < len(argv):
op["count"] = int(argv[i + 1]); i += 2
elif a == "--n-fix" and i + 1 < len(argv):
op["n-fix"] = int(argv[i + 1]); i += 2
elif a == "--each" and i + 1 < len(argv):
op["each"] = int(argv[i + 1]); i += 2
elif a == "--tpl" and i + 1 < len(argv):
op["tpl"] = argv[i + 1]; i += 2
elif a == "--days" and i + 1 < len(argv):
op["days"] = int(argv[i + 1]); i += 2
elif a == "--note" and i + 1 < len(argv):
op["note"] = argv[i + 1]; i += 2
elif a == "--lock":
op["lock"] = True; i += 1
elif a == "--kind" and i + 1 < len(argv):
op["kind"] = argv[i + 1]; i += 2 # render/standee/keychain/poster…
elif a == "--n-free":
op["free"] = True; i += 1 # 不限张数
elif a == "--no-direct":
op["direct"] = False; i += 1
else:
i += 1
try:
bid, codes = S.gift_batch_new(
name, count=op["count"], n_fix=op["n-fix"], n_free=op["free"],
tpl=op["tpl"], lock_tpl=op["lock"], days=op["days"],
note=op["note"], kind=op["kind"], direct=op["direct"], each=op["each"])
except ValueError as e:
raise SystemExit(str(e))
print("批次 id:%s(把这个贴给别人也行:福利页会自动列出来)" % bid)
print("生了 %d 张券。" % len(codes))
show_all()
elif sub == "add" and len(argv) > 1:
bid = argv[1]
n, direct = 20, None
i = 2
while i < len(argv):
if argv[i] == "--count" and i + 1 < len(argv):
n = int(argv[i + 1]); i += 2
elif argv[i] == "--no-direct":
direct = False; i += 1
elif argv[i] == "--direct":
direct = True; i += 1
else:
i += 1
try:
got = S.gift_batch_add(bid, n, direct=direct)
except ValueError as e:
raise SystemExit(str(e))
print("补了 %d 张(批次 %s)" % (len(got), bid))
show_all()
elif sub == "off" and len(argv) > 1:
try:
S.gift_batch_off(argv[1])
except ValueError as e:
raise SystemExit(str(e))
print("已收摊(已领到手的券照常用):%s" % argv[1])
show_all()
else:
raise SystemExit("用法见文件头注释")
CMDS = {"gen": cmd_gen, "codes": cmd_codes, "ls": cmd_ls, "show": cmd_show,
"gift": cmd_gift,
"price": cmd_price,
"retry": cmd_retry, "calls": cmd_calls, "sweep": cmd_sweep, "stat": cmd_stat,
"audit": cmd_audit, "activate": cmd_activate, "pending": cmd_pending,
"edit": cmd_edit}
if __name__ == "__main__":
if len(sys.argv) < 2 or sys.argv[1] not in CMDS:
print(__doc__)
sys.exit(1)
CMDS[sys.argv[1]](sys.argv[2:])
+133
View File
@@ -0,0 +1,133 @@
# -*- coding: utf-8 -*-
"""PNG 结构核验 —— 防「夹带私货」:有人在文件尾部或元数据块里塞任意数据,
改图看不出来,但能夹带任意字节(图片里藏文件 / 藏提示词 / 藏脚本)。
**只做结构判断,不解码像素** —— 零依赖、零成本、零误判。
判定分三档:
拒(reject)
* 签名不对 / 没有 IHDR / 块结构损坏或截断
* **IEND 之后还有字节** ← 最常见的尾部夹带
* 未知的「关键块」(首字母大写且不在白名单)→ 后面可能跟着必须解析的语义
* **APNG(acTL)** → 多帧能藏额外画面,剥掉 acTL 会留下孤儿 fcTL
剥(strip,不算错)
* tEXt / zTXt / iTXt / eXIf / tIME → 元数据,很多编辑器会自动加,剥掉不影响成图
过(pass)
* IHDR / PLTE / IDAT / IEND / tRNS / gAMA / cHRM / sRGB / iCCP / bKGD / pHYs / sBIT
⚠️ 这份逻辑在前端也有一份镜像(`skincheck.js` 的 `checkPngBytes`)。
两边必须一致 —— 前端负责**拦**(给人看的原因),后端负责**剥**(存下来的是干净字节)。
改一边记得改另一边,`tests/png_struct_test.py` 里有共享用例。
"""
import struct
import zlib
SIG = b"\x89PNG\r\n\x1a\n"
# 直接剥掉的辅助块(不报错)
STRIP = {b"tEXt", b"zTXt", b"iTXt", b"eXIf", b"tIME", b"sPLT", b"hIST"}
# 允许出现的关键块
CRITICAL_OK = {b"IHDR", b"PLTE", b"IDAT", b"IEND"}
MAX_CHUNKS = 4096 # 防"超多小块"这种结构型 DoS
def scan(data):
"""核验并清洗。
返回 (ok, reason, clean_bytes, notes)
ok=False 时 clean 为 None
"""
notes = []
if not isinstance(data, (bytes, bytearray)):
return False, "数据格式不对", None, notes
data = bytes(data)
if len(data) < 8 + 25 or data[:8] != SIG:
return False, "不是 PNG 文件", None, notes
off = 8
out = bytearray(SIG)
n_chunks = 0
seen_ihdr = False
seen_idat = False
seen_iend = False
while off < len(data):
if n_chunks > MAX_CHUNKS:
return False, "PNG 结构异常(块数量过多)", None, notes
if off + 8 > len(data):
return False, "PNG 文件损坏(块头不完整)", None, notes
(ln,) = struct.unpack(">I", data[off:off + 4])
ctype = data[off + 4:off + 8]
end = off + 12 + ln
if ln > len(data) or end > len(data):
return False, "PNG 文件损坏(块数据不完整)", None, notes
chunk = data[off:end]
n_chunks += 1
# CRC 自检(不一致只记一笔,不拒 —— 目标是防夹带,不是查完整性)
try:
want = struct.unpack(">I", chunk[-4:])[0]
got = zlib.crc32(chunk[4:-4]) & 0xFFFFFFFF
if want != got:
notes.append("块 %s 的 CRC 对不上" % ctype.decode("latin-1"))
except Exception:
pass
if ctype == b"IHDR":
if len(out) != 8:
return False, "PNG 结构异常(IHDR 不在最前)", None, notes
seen_ihdr = True
out += chunk
elif ctype == b"IEND":
seen_iend = True
tail = len(data) - end # ← 尾部夹带就在这里露馅
if tail > 0:
return False, ("图片尾部夹带了 %d 字节额外数据(正常 PNG 到 IEND 就该结束)" % tail), None, notes
out += chunk
off = end
break
elif ctype == b"acTL":
return False, "这是动画 PNG(APNG),请用普通静态 PNG", None, notes
elif ctype == b"IDAT":
seen_idat = True
out += chunk
elif ctype in (b"PLTE", b"tRNS", b"gAMA", b"cHRM", b"sRGB", b"iCCP", b"bKGD", b"pHYs", b"sBIT"):
out += chunk
elif ctype in STRIP:
notes.append("已剥掉元数据块 %s" % ctype.decode("latin-1"))
else:
critical = not (ctype[0] & 0x20) # PNG 规范:首字母大写 = 关键块
if critical and ctype not in CRITICAL_OK:
return False, ("图片里有无法识别的内容块 %s" % ctype.decode("latin-1", "replace")), None, notes
notes.append("已剥掉附加块 %s" % ctype.decode("latin-1", "replace"))
off = end
if not seen_ihdr:
return False, "PNG 缺少 IHDR(不是完整图片)", None, notes
if not seen_idat:
return False, "PNG 缺少图像数据(IDAT)", None, notes
if not seen_iend:
return False, "PNG 没有正常结束(缺 IEND)", None, notes
return True, "", bytes(out), notes
def size_of(data):
"""只读 IHDR 拿宽高(不解码像素)。"""
if len(data) < 33 or data[:8] != SIG or data[12:16] != b"IHDR":
return None
w, h = struct.unpack(">II", data[16:24])
return w, h
File diff suppressed because it is too large Load Diff
+247
View File
@@ -0,0 +1,247 @@
# 交接说明 · 网站后端(卡密 / 自助渲染下单)
> **交付方**:苏达(网站运维与技术提供)
> **收件方**:外部协作者
> **日期**:2026-10-05
> **一句话**:这是一个**零依赖单进程**的下单/卡密/队列后端,跑在一台小机器上。
> 请你重点看**安全与并发**,并给我们**问题分析 + 改正意见**(见最后一节)。
---
## 一、这一份是什么
「自助模板渲染」的**服务端**:买家在网页挑模板、传皮肤、填卡密下单;
服务器登记订单、排队;家里那台渲染机上线后自动领单、出图、回传;
买家再回来下载。**目标是无人值守** —— 不用人 24 小时盯着。
```
买家 → 网页(本地质检→选模板→填卡密→核对)→ POST /api/submit
↓ 核销卡密 + 落盘订单目录
服务器 → 队列(订单 meta 里的一个 state 字段:waiting/working/done/failed)
渲染机 → 每 20s:POST /hb → POST /claim → GET /skin/<单号>
→ Blender 渲染 → POST /progress(进度)→ POST /finish(一张一次)
买家 → GET /api/order/<单号>?t=<口令> → 下载 /api/dl/<单号>/<i>?t=<口令>
```
**为什么"渲染机是主动出站"**:家里那台机器没有公网入口,所以**服务器从不连它**,
全靠它自己定时来拉。心跳超过阈值没更新 → 页面显示「渲染机离线」。
---
## 二、技术栈与运行方式
| 项 | 值 |
|---|---|
| 语言 / 依赖 | **Python 3,纯标准库,零第三方依赖**(连 Web 框架都没用,`BaseHTTPRequestHandler`) |
| 进程 | 单进程,由 systemd 托管;内存上限被 cgroup 卡住(小机器上防它吃爆) |
| 监听 | **只绑回环**,公网由 nginx 反代过去(后端自己不对外开端口) |
| 账号 | 跑在专用非 root 用户下 |
| 数据 | 全在本地文件 + 一个 SQLite(无外部服务) |
| 规模 | 单机单进程,日单量个位数到几十 |
**为什么不用框架**:这台机器很小(1G 多内存),装一个 Web 框架 + 一堆传递依赖不划算,
而且这台机器**不允许跑重活**(视频转码这类会把它拖死)。纯标准库启动快、内存稳。
---
## 三、文件清单
| 文件 | 行数 | 干什么 |
|---|---|---|
| `server.py` | ~3100 | **全部服务端逻辑**:路由、订单状态机、卡密生命周期、限流、PNG 结构核验的调用方、爱发电回调、打包下载、小票生成 |
| `admin.py` | ~540 | 命令行管理工具:发卡密 / 看队列 / 重渲 / 清过期 / 审计被拦记录 |
| `pngcheck.py` | ~130 | PNG **结构**核验(不解码像素):防「夹带私货」——尾部塞字节、未知关键块、APNG |
> 这三个文件是**自足**的:没有 import 本项目之外的模块。
---
## 四、对外接口
全部挂在 `/order/api/` 下(nginx 反代);下面路径已按脱敏规则替换过前缀,**看形状别看字面**。
| 方法 | 路径 | 谁用 | 说明 |
|---|---|---|---|
| GET | `/api/status` | 页面轮询 | 渲染机在线?队列长度 |
| POST | `/api/submit` | 页面 | 皮肤(base64) + 模板数组 + 卡密数组 + 臂型 → 返回 `{order, token}` |
| POST | `/api/add-skin` | 页面 | 追补一张皮肤(多皮肤单) |
| POST | `/api/set-templates` | 页面 | 改/补模板(可只改某一张皮肤的) |
| GET | `/api/order/<单号>?t=<口令>` | 页面 | 状态 + 可下载文件清单 + 进度 + 预计耗时 |
| GET | `/api/dl/<单号>/<i>?t=<口令>` | 买家 | 下载成品(未收货只能拿预览) |
| GET | `/api/zip/<单号>?t=` | 买家 | 整单原图打 zip(先落临时文件再边读边发) |
| GET | `/api/receipt/<单号>?t=` | 买家 | 小票纯文本(`&dl=1` 变附件) |
| POST | `/api/accept` | 买家 | 确认收货 → 才放原图 |
| POST | `/api/paid` | 买家 | 「我付好了」 |
| POST | `/api/activate` | 买家 | 用卡密**激活自己那一单**(码认单,不开新单) |
| POST | `/api/redo` | 买家 | 重渲(支持只重出勾中的那几张) |
| POST | `/api/call` | 页面 | 呼叫店主(同 IP 限次) |
| POST | `/api/feedback` | 页面 | 反馈(落盘 + 通知) |
| GET | `/api/payinfo` | 页面 | 付款方式(链接/收款码) |
| POST | `/api/payplatform-hook` | 支付平台回调 | **不验签,改成拿开放接口反查这笔单**(见下) |
| POST | `/api/hb` `/api/claim` `/api/skin/<单号>` `/api/progress` `/api/finish` `/api/fail` | **渲染机** | 都要请求头里的 worker token |
| GET/POST | `/api/admin/*` | **本机后台面板** | 头里带 admin token **且**来源 IP 必须是家里出口 IP |
### 支付回调的处理顺序(这段是重点,欢迎挑刺)
```
① 标题含"测试" → 只记账
② 幂等:同一平台单号重推 → 回同一张卡密
③ 反查不到 / 未付款 → 只记账 + 标 need_human,**绝不发卡密**
④ 金额比对:
少付(paid + 0.005 < need)→ **闸门拦死**,不激活不发码,记 need_human
多付 → 照样激活出图,但记 over 待人工看一眼
⑤ 认单优先级:自定义订单号 > 留言里的卡密 > 留言里的订单号 > 「只有一笔待付款单金额对得上」
(两笔及以上一律人工,绝不乱认)
```
---
## 五、数据形状(都是文件/JSON,没有数据库表)
| 路径 | 内容 |
|---|---|
| `<DATA_DIR>/codes.json` | 卡密池:`{码: {state, platform, tpl, n_fix, n_free, n_max, lock_tpl, oid, order, batch}}` |
| `<DATA_DIR>/orders/<单号>/meta.json` | 订单:状态、皮肤数组、模板、金额、时间、条款留证、进度 |
| `<DATA_DIR>/orders/<单号>/skins/` | 买家皮肤原图(落盘前已过 PNG 结构核验并剥掉元数据块) |
| `<DATA_DIR>/orders/<单号>/out/` | 成品(标准压缩 + 无压缩 两个版本/张) |
| `<DATA_DIR>/worker_token`、`admin_token` | 两把**互不通用**的令牌(文件权限 600) |
| `<DATA_DIR>/home_ips.json` | 渲染机心跳认出来的「家里的出口 IP」 |
| `<DATA_DIR>/calls.jsonl` | 「呼叫店主」记录 |
| `<DATA_DIR>/upload.log` 等 | 审计留痕 |
### 卡密生命周期(**激活 ≠ 核销**,这是刻意分开的)
```
active 可用
↓ 买家点提交
bound **已激活** —— 被这一单占住,不能用于别的单;但还没核销
↓ 成品开放下载满 72 小时(或直发单从渲完起算)
used **已核销** —— 终态
inactive 停用(网页单等付款 / 手动停用)
```
⚠️ 触发核销的只有两处,**删文件之前必须先核销**,否则文件没了码还挂在"已激活"。
---
## 六、已经做了的防护(请你对着挑漏)
| 防护 | 做法 |
|---|---|
| 卡密暴力破解 | 31 字符取 12 位 ≈ 7.9e17 组合;**单 IP 连错 15 次 → 冷却 15 分钟** |
| 灌单 | 单 IP 10 分钟最多开 6 单;提交接口在 nginx 上单独限流 |
| 探测 | **「订单不存在」与「口令错」返回同一个 404**(不承认站上有这单) |
| 占盘 | 磁盘剩余低于阈值**停止收单** |
| 夹带私货 | PNG 结构核验:拒尾部追加 / 未知关键块 / APNG;剥掉文本与 EXIF 类元数据块 |
| 取皮肤 | 必须带 worker token |
| 管理接口 | **两道门**:token + 来源 IP 必须是家里出口 IP(公网别处扫到也是 403) |
| 路径穿越 | slug 白名单 + realpath 前缀校验 |
---
## 七、⚠️ 脱敏说明(**重要:这份代码不能直接跑**)
按我们的出站纪律,**所有指向真实环境的值都换成了占位**:
| 类别 | 替换成 |
|---|---|
| 站点域名 / 支付平台域名 | `shop.example.com` / `pay-platform.example` |
| 监听端口、面板端口 | 中性数字(`8080`/`8081`/`8082`…)—— **不是真值** |
| 数据 / 程序 / 工作目录 | `<DATA_DIR>` / `<APP_DIR>` / `<WORKER_DIR>` |
| Windows 盘符路径 | `<WIN-PATH>` / `<ARCHIVE_DIR>` / `<TOOLS_DIR>` |
| 家里出口 IP / 局域网 IP | `<HOME-LAN-IP>` / `<LOCAL-IP>` |
| 通配绑定地址 | `<ALL-INTERFACES>` |
| 密钥 / 令牌**值** | 本来就没有硬编码——全走文件与环境变量,所以代码里是干净的 |
**保留未换的**:`localhost`(回环,通用值)、渲染分辨率 `1000/1024/2048/4096`(业务常量)、
以及**品牌笔名**(属公开署名)。
**包里没有的**(⚠️ 别去找,是刻意不给):
- 任何真实卡密、订单、买家皮肤与成品图
- 两把令牌、任何密钥、任何账号凭据
- 数据库/运行数据、备份
- 私有仓库地址、内部文档
---
## 八、⭐ 我们要你交给我们的东西(**这一份的主要目的**)
请你读完之后**回一份文档**(放在同一个仓库里就行,文件名 `回执-<你的名字>.md`),至少包含三部分:
1. **问题分析** —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。
请**尽量指到具体函数/行**,并说清**触发条件**(什么输入、什么并发时序会踩到)。
2. **改正意见** —— 每条给**你建议怎么改**(不一定要写代码,说清思路和代价也行)。
如果有**更简单的整体方案**(比如"这段根本该换个做法"),也请直说,别客气。
3. **你改了什么** —— 如果你直接动手改了,请逐条列:
```
文件 / 函数:
为什么改:
改成什么(一句话说清):
有没有动到接口路径、请求/响应字段、数据格式(**这三样动了我们必须知道**):
你怎么验证的(跑过什么、看到什么):
```
⚠️ **改了接口/数据格式一定要单独标出来** —— 渲染机那边是另一台机器上的另一份代码,
两边不同步会**静默出不来图**。
**另外请你顺手回答两个具体问题**(我们自己拿不准):
- 爱发电那条线**"不验签、改成拿开放接口反查"**,你认为够不够硬?有没有更好的做法?
- 订单状态机(`unpaid → paid → waiting → working → done/failed`)在**部分失败**时
(比如 3 张图渲出 2 张)你建议怎么收口?
---
## 九、我们的思路与方法(**请你连这套做法一起评**)
代码能看出的是一部分;**为什么这么做、踩过什么坑**,在代码里看不到。这一节补上,
**并且希望你连"做法"本身一起挑** —— 如果我们整套思路就是错的,那比某个函数写错更要紧。
### 9.1 我们给自己定的几条硬规矩
| 规矩 | 为什么 |
|---|---|
| **无人值守优先**:机器的活不该让人 24 小时待命 | 这行的买家半夜下单是常态,靠人盯必然漏 |
| **正常用户一步都不多加**:每加一道防探测,先问"正常买家会不会被误伤" | 防的是坏人,误伤的是给你钱的人。两者冲突时**先保买家** |
| **收钱的数字一律以服务器订单为准**,本地状态只能当兜底 | 踩过:恢复订单时本地状态是空的,按本地算出错的金额去拼付款链接 → 买家少付 → 闸门拦死。**同一行显示两个来源的数,必然自相矛盾** |
| **状态话术不许骗人** | 踩过:没付款的单子被兜底文案说成"正在排队"。宁可说"没取到订单信息",也不给假安心 |
| **出错要说清是什么、下一步怎么办**,不引导用户猜 | 报错是给人看的,不是给日志看的 |
| **同一件事的逻辑只写一处** | "CLI 一套、后台面板一套"必然漂移 —— 出现过面板和命令行生成出两种卡密 |
### 9.2 我们干活的方法(改这块代码时照着来)
1. **改一处 → 顺着所有调用点核一遍**。可见性逻辑被好几个入口调用,改了一处、
别的入口还传旧参数 → 出现"导航正常、首页却说没有可见内容"这种**看着像站坏了**的现象。
2. **同一个东西存在两处时,先问"读取方是按哪个字段找的"**。改写入方不改读取方 =
写进去了、读的还是旧的(踩过:换了皮肤文件、但路径字段没跟着改,买家看到"重渲了还是旧图")。
3. **前端必须真的在浏览器里点一遍**。有一批 bug 在 API 层**根本测不出来**
(页面上某个渲染函数调了不存在的名字 → 每次进第 2 步就抛异常 → 页面看着"就是没反应")。
4. **部署完要核对"跑的是不是新代码"**,不是"部署脚本说成功了"。
踩过:脚本全程报成功、功能静默缺失 —— 旧进程还活着,计划任务的"运行"不会替换它。
5. **自测的每一个负例各用一份新数据**。复用同一份的话,第一条成功就把它消耗了,
后面几条测的其实是"已经用过了"—— **全绿,但什么都没测到**。
6. **测完必须清场**。测试产生的记录不许留在管理员看得见的列表里。
### 9.3 我们付过学费的坑(这些是"不要重复踩"清单)
- **静默失败最贵**:不报错、不崩,就是没效果 —— 比抛异常难查十倍。
所以我们宁可让它**响亮地失败**(比如离线就不显示预计时间、宁可说"没取到")。
- **显示层会骗人**:订单本身算对了,但界面从另一个来源取数 → 用户看到的是错的。
**凡是"从 A 推导出 B"的函数,在别处读 B 之前都要先调一次它**。
- **文件重复投递**:渲染机与服务器之间"一张图一次"回传,是因为一次全传会撞体积上限。
- **重试要有上限也能收敛**:部分失败必须显式收尾,否则订单会永远停在"渲染中"、被反复重渲。
### 9.4 我们最想要你评的三件"做法"
1. **"不验签、改成拿开放接口反查"**这个取舍,你认同吗?(我们手头没有对方的公钥,与其猜算法不如反查)
2. **订单状态机在部分失败时怎么收口**(3 张渲出 2 张)—— 我们现在靠"显式收尾",你觉得够不够。
3. **这套"单文件纯标准库"的写法**:好处是零依赖零安装、小机器跑得动;
代价是路由/校验/序列化全得自己写。**换你,你会不会上框架?** 请直说。
---
## 十、边界
- 这份是**私有交付**,**请勿外传 / 勿镜像 / 勿公开**(含截图、片段)。
- 里面是**占位值**,请不要替换成任何真实地址再提交回来。
- 有看不懂的先问,别猜着改 —— 猜错了我们这边会静默坏掉。
- 你可以自由重构,但**动了接口/数据格式要按第 8 节单独标出来**。