chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。一、docs 结构整改（整改 #14）根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录树并存于 docs/，共 791 文件、双分类体系冲突。修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回，与线上一致，分叉隐患消除（已 docker compose config 校验通过）防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00
parent 5a77a89ab1
commit facc04aa65
573 changed files with 129347 additions and 909 deletions
@@ -0,0 +1,76 @@
+# 部署运维工具箱
+
+> **版本**: v1.0 | **日期**: 2026-07-10 | **维护人**: 宋献
+> **定位**: 部署运维过程中可复用的脚本、配置模板和调试工具的统一存放点。
+> **规则**: 每次故障排查或部署完成后，可复用的工具应归档到此目录并在本 README 中登记。
+
+---
+
+## 工具索引
+
+### 上传部署工具
+
+| 工具 | 用途 | 使用方式 |
+|------|------|----------|
+| `fast_upload.py` | 堡垒机大文件快速上传（已被 jumpserver-V2 的 psftp 通道替代，仅供参考） | `python fast_upload.py <本地文件> <远程路径>` |
+| `deploy_to_container.py` | 一键部署到 Docker 容器（打包→上传→cp→重启） | `python deploy_to_container.py <服务名> <本地路径> <容器路径>` |
+
+### Nginx 配置模板
+
+| 工具 | 用途 | 使用方式 |
+|------|------|----------|
+| `nginx-access-control.conf` | 三端访问控制配置模板（企微 UA OR IP 白名单双条件放行 + CSP 头） | 上传到服务器 `/opt/wecom-it-desk/nginx/nginx.conf` 后 `docker restart wecom_it_nginx` |
+
+### 调试检查工具
+
+| 工具 | 用途 | 使用方式 |
+|------|------|----------|
+| `check_html.py` | Python f-string HTML 花括号平衡检查器（排查 `{{ }}` 转义问题） | `python check_html.py <file.py>` |
+| `render_test.py` | 容器内 HTML 渲染验证（模拟 f-string 渲染并输出实际 HTML/JS） | `docker exec wecom_it_backend python /tmp/render_test.py` |
+| `extract_html.py` | 从 Python f-string 中提取 HTML 模板到独立文件 | `python extract_html.py <file.py>` |
+
+### 历史修复脚本（archive/）
+
+以下脚本为一次性修复用途，保留在 `archive/` 子目录中供参考，不建议直接复用。
+
+| 脚本 | 修复场景 | 日期 |
+|------|----------|------|
+| `fix_admin_role.py` | 修复扫码登录角色写死为 agent 的问题 | 2026-07-08 |
+| `fix_compose_redis.py` / `fix_compose_redis2.py` | 修复 docker-compose Redis 密码 URL 编码 | 2026-07-07 |
+| `fix_itdesk.py` / `fix_itdesk2.py` / `fix_itdesk3.py` | 修复 nginx /itdesk/ 路由问题 | 2026-07-08 |
+| `patch.py` / `patch-mini.py` / `patch-redis-url.py` | Redis 密码 URL 编码补丁 | 2026-07-02 |
+| `update_password.py` | 数据库密码更新脚本 | 2026-07-05 |
+| `check_logs.py` / `check_roles.py` / `verify_logs.py` | 日志和角色检查（一次性诊断） | 2026-07-08~09 |
+| `upload_chunked.py` / `upload_split.py` | 早期分块上传方案（已被 fast_upload.py 替代） | 2026-07-08 |
+| `nginx_*.conf` / `itdesk-nginx-block.conf` | 历史 nginx 配置快照 | 2026-07-06~08 |
+| `extract_and_migrate.py` / `_ctrt_transform.py` | 数据迁移和格式转换 | 2026-07-06 |
+
+---
+
+## 工具沉淀流程
+
+1. **排查完成** → 评估是否有可复用的脚本/配置模板
+2. **归档** → 复制到 `toolbox/`（活跃工具）或 `toolbox/archive/`（历史脚本）
+3. **登记** → 在本 README 的工具索引表中添加条目
+4. **清理** → 删除项目根目录的临时文件（渲染输出、中间产物等）
+
+## 堡垒机使用说明
+
+所有工具涉及服务器操作时，通过堡垒机（`sxn@10.212.189.210:2222`）执行：
+- 统一使用 `v2_ops.py`（jumpserver-V2 技能）
+- 详见 `docs/04-运维文档/部署运维/11-堡垒机运维工具.md`
+
+---
+
+## 相关文档
+
+| 文档 | 位置 |
+|------|------|
+| 标准故障排查手册 | `docs/04-运维文档/部署运维/00-标准故障排查手册.md` |
+| 堡垒机运维工具 | `docs/04-运维文档/部署运维/11-堡垒机运维工具.md` |
+| 项目管理 SOP | `docs/07-项目管理/IT智能服务台-标准作业流程SOP.md` |
+| Nginx 基线配置 | `docs/04-运维文档/部署运维/01-nginx-prod-baseline-20260708.conf` |
+
+---
+
+> **维护说明**: 新增工具时请同步更新本 README。archive/ 中的脚本仅供历史参考，不保证可用性。
@@ -0,0 +1,19 @@
+import re
+
+with open(
+    r'D:\资料\03-项目开发\wecom_it_smart_desk\backend\app\api\auth_qrcode.py',
+    'r',
+    encoding='utf-8',
+) as f:
+    content = f.read()
+
+match = re.search(r'html = f"""(.+?)"""', content, re.DOTALL)
+if match:
+    html = match.group(1)
+    print('HTML length:', len(html))
+    out_path = r'D:\资料\03-项目开发\wecom_it_smart_desk\tmp_scan_html.html'
+    with open(out_path, 'w', encoding='utf-8') as out:
+        out.write(html)
+    print('Saved to', out_path)
+else:
+    print('HTML template not found')
@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""
+快速 base64 上传脚本 — 大分块版本（已废弃）
+将本地文件通过 JumpServer PTY base64 通道上传到远程服务器
+使用 8000 字符/块（远大于 jms_ops.py 的 500 字符），大幅减少命令数
+
+⚠️ 此脚本已废弃，请使用 jumpserver-V2 的 v2_ops.py upload 命令（psftp 通道）
+"""
+import sys
+import base64
+import hashlib
+from pathlib import Path
+
+# 添加 jms_ops.py 所在目录
+SKILL_DIR = Path(r"C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts")
+sys.path.insert(0, str(SKILL_DIR))
+
+# 导入 jms_ops 中的核心函数
+from jms_ops import get_connection_tokens, PlinkSession
+
+
+def fast_upload(local_path: str, remote_path: str, chunk_size: int = 8000):
+    """大分块 base64 上传"""
+    local_file = Path(local_path)
+    if not local_file.exists():
+        print(f"ERROR: file not found: {local_path}")
+        return False
+
+    local_data = local_file.read_bytes()
+    local_md5 = hashlib.md5(local_data).hexdigest()
+    b64_data = base64.b64encode(local_data).decode("ascii")
+
+    # 分块
+    chunks = [b64_data[i:i+chunk_size] for i in range(0, len(b64_data), chunk_size)]
+    total_chunks = len(chunks)
+
+    print(f"File: {local_file.name}")
+    print(f"Size: {len(local_data)} bytes")
+    print(f"Base64: {len(b64_data)} chars")
+    print(f"Chunks: {total_chunks} x {chunk_size} chars")
+    print(f"MD5: {local_md5}")
+    print(f"Target: {remote_path}")
+    print()
+
+    # 获取 token + 启动会话
+    tokens = get_connection_tokens(1)
+    if not tokens:
+        print("ERROR: failed to get connection tokens")
+        return False
+
+    token_id, token_secret = tokens[0]
+    session = PlinkSession(f"JMS-{token_id}", token_secret)
+    if not session.connect():
+        print("ERROR: failed to connect session")
+        return False
+
+    try:
+        # 1. 清空目标文件
+        print("Clearing target file...")
+        session.run_command(f"> {remote_path}", timeout=5)
+
+        # 2. 逐块追加
+        for i, chunk in enumerate(chunks):
+            # 用 printf 避免 echo 的换行符问题
+            cmd = f"printf '%s' '{chunk}' >> {remote_path}.b64"
+            r = session.run_command(cmd, timeout=10)
+            if not r["success"]:
+                print(f"  FAIL chunk {i+1}/{total_chunks}")
+                return False
+
+            # 进度报告
+            if (i+1) % 20 == 0 or (i+1) == total_chunks:
+                pct = (i+1) * 100 // total_chunks
+                print(f"  [{pct:3d}%] chunk {i+1}/{total_chunks}")
+
+        # 3. base64 解码
+        print(f"\nDecoding base64 -> {remote_path}...")
+        r = session.run_command(f"base64 -d {remote_path}.b64 > {remote_path}", timeout=30)
+        if not r["success"]:
+            print(f"  WARN decode result: {r}")
+
+        # 4. 验证大小
+        print("Verifying size...")
+        r = session.run_command(f"wc -c < {remote_path}", timeout=5)
+        if r["success"]:
+            remote_size_str = r["output"].strip()
+            remote_size = int(remote_size_str) if remote_size_str.isdigit() else -1
+            if remote_size == len(local_data):
+                print(f"  OK size match: {remote_size} bytes")
+            else:
+                print(f"  SIZE MISMATCH: local={len(local_data)}, remote={remote_size}")
+                return False
+        else:
+            print(f"  WARN cannot verify size: {r}")
+            return True  # 仍然认为成功
+
+        # 5. MD5 验证
+        print("Verifying MD5...")
+        r = session.run_command(f"md5sum {remote_path}", timeout=10)
+        if r["success"]:
+            remote_md5 = r["output"].split()[0]
+            if remote_md5 == local_md5:
+                print(f"  OK MD5 match: {remote_md5}")
+            else:
+                print(f"  MD5 MISMATCH: local={local_md5}, remote={remote_md5}")
+                # 大小匹配但 MD5 不匹配，可能是 PTY 换行符问题
+                print("  (size matches, trying gzip test instead)")
+                r2 = session.run_command(f"gzip -t {remote_path} 2>&1 && echo GZIP_OK || echo GZIP_FAIL", timeout=10)
+                if r2["success"] and "GZIP_OK" in r2["output"]:
+                    print("  OK gzip integrity test passed")
+                    # 清理临时文件
+                    session.run_command(f"rm -f {remote_path}.b64", timeout=5)
+                    return True
+                else:
+                    print(f"  GZIP FAIL: {r2}")
+                    return False
+        else:
+            print(f"  WARN cannot verify MD5")
+
+        # 6. 清理临时文件
+        session.run_command(f"rm -f {remote_path}.b64", timeout=5)
+        print("\nUpload complete!")
+        return True
+
+    finally:
+        session.close()
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Fast base64 upload via JumpServer PTY")
+    parser.add_argument("local", help="Local file path")
+    parser.add_argument("remote", help="Remote file path")
+    parser.add_argument("--chunk-size", type=int, default=8000, help="Chunk size in chars (default: 8000)")
+    args = parser.parse_args()
+
+    success = fast_upload(args.local, args.remote, args.chunk_size)
+    sys.exit(0 if success else 1)
@@ -0,0 +1,181 @@
+"""在容器内运行，渲染 scan 端点的实际 HTML 输出"""
+import sys
+sys.path.insert(0, '/app')
+
+# 模拟 f-string 中的变量
+user_name = "测试用户"
+jsapi_signature = "test_sig_abc123"
+jsapi_timestamp = 1752105600
+jsapi_nonce = "test_nonce_xyz"
+jsapi_appid = "ww_test_corp_id"
+current_url = "https://itsupport.servyou.com.cn/api/auth_qrcode/scan?code=test&state=test"
+
+html = f"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>登录成功 - IT智能服务台</title>
+<style>
+* {{ margin: 0; padding: 0; box-sizing: border-box; }}
+body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: linear-gradient(135deg, #07C160 0%, #06AD56 100%); min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 20px; }}
+.card {{ background: rgba(255,255,255,0.95); border-radius: 20px; padding: 48px 32px; max-width: 360px; width: 100%; text-align: center; box-shadow: 0 20px 60px rgba(0,0,0,0.3); }}
+.check {{ width: 64px; height: 64px; margin: 0 auto 16px; }}
+.title {{ color: #1f2937; font-size: 24px; font-weight: 600; margin-bottom: 8px; }}
+.subtitle {{ color: #6b7280; font-size: 14px; margin-bottom: 24px; }}
+.status {{ display: inline-flex; align-items: center; gap: 6px; background: #dcfce7; color: #166534; padding: 10px 20px; border-radius: 50px; font-size: 14px; font-weight: 500; }}
+.footer {{ margin-top: 20px; color: #9ca3af; font-size: 12px; }}
+.back-btn {{ display: none; margin-top: 20px; padding: 12px 32px; background: #07C160; color: white; border: none; border-radius: 50px; font-size: 16px; font-weight: 500; cursor: pointer; }}
+.debug {{ margin-top: 16px; color: #6b7280; font-size: 11px; line-height: 1.6; word-break: break-all; text-align: left; background: #f3f4f6; padding: 10px 12px; border-radius: 8px; }}
+.debug b {{ color: #07C160; }}
+</style>
+</head>
+<body>
+<div class="card">
+<svg class="check" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="32" cy="32" r="30" fill="#07C160" stroke="#06AD56" stroke-width="4"/>
+<path d="M20 32l8 8 16-16" stroke="white" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+<h1 class="title">登录成功</h1>
+<div class="status">已自动确认登录</div>
+<p class="subtitle">你好，{user_name}<br>请返回电脑端查看</p>
+<button class="back-btn" id="backBtn" onclick="manualClose()">点击返回企微</button>
+<div class="footer">页面即将自动关闭 · 税友集团</div>
+<div class="debug" id="debugInfo">
+<b>签名:</b> {'成功' if jsapi_signature else '未生成'}<br>
+<b>URL:</b> {current_url}<br>
+<b>状态:</b> <span id="jsStatus">JS加载中...</span>
+</div>
+</div>
+<script>
+(function() {{
+    var statusEl = document.getElementById('jsStatus');
+    var btnEl = document.getElementById('backBtn');
+    var startTime = Date.now();
+    var tried = {{}};
+
+    function setStatus(msg) {{
+        if (statusEl) statusEl.textContent = msg + ' (' + (Date.now() - startTime) + 'ms)';
+    }}
+
+    function showBtn() {{
+        if (btnEl) btnEl.style.display = 'inline-block';
+    }}
+
+    function tryClose(forceShowBtn) {{
+        setStatus('尝试关闭');
+
+        if (!tried.wxClose && typeof wx !== 'undefined' && wx.closeWindow) {{
+            tried.wxClose = true;
+            try {{
+                setStatus('wx.closeWindow');
+                wx.closeWindow();
+                return true;
+            }} catch(e) {{ setStatus('wx.closeWindow失败:' + (e.message || e)); }}
+        }}
+
+        if (!tried.wxInvoke && typeof wx !== 'undefined' && wx.invoke) {{
+            tried.wxInvoke = true;
+            try {{
+                setStatus('wx.invoke closeWindow');
+                wx.invoke('closeWindow', {{}}, function(){{}});
+                return true;
+            }} catch(e) {{ setStatus('wx.invoke失败:' + (e.message || e)); }}
+        }}
+
+        if (!tried.jsBridge && typeof WeixinJSBridge !== 'undefined' && WeixinJSBridge.call) {{
+            tried.jsBridge = true;
+            try {{
+                setStatus('WeixinJSBridge.closeWindow');
+                WeixinJSBridge.call('closeWindow');
+                return true;
+            }} catch(e) {{ setStatus('JSBridge失败:' + (e.message || e)); }}
+        }}
+
+        if (!tried.windowClose) {{
+            tried.windowClose = true;
+            try {{
+                setStatus('window.close');
+                window.close();
+                return true;
+            }} catch(e) {{}}
+        }}
+
+        if (!tried.historyBack) {{
+            tried.historyBack = true;
+            try {{
+                setStatus('history.back');
+                history.back();
+                return true;
+            }} catch(e) {{}}
+        }}
+
+        if (forceShowBtn) {{
+            setStatus('无法自动关闭，请手动返回');
+            showBtn();
+        }}
+        return false;
+    }}
+
+    function manualClose() {{
+        tryClose(true);
+    }}
+
+    var checkCount = 0;
+    var maxChecks = 50;
+    var interval = setInterval(function() {{
+        checkCount++;
+        var hasWx = typeof wx !== 'undefined';
+        var hasBridge = typeof WeixinJSBridge !== 'undefined';
+        setStatus('检测中 wx=' + hasWx + ' bridge=' + hasBridge + ' count=' + checkCount);
+
+        if (hasWx || hasBridge) {{
+            clearInterval(interval);
+            setStatus('已检测到关闭API，1秒后尝试关闭');
+            setTimeout(function() {{
+                tryClose(true);
+            }}, 1000);
+            return;
+        }}
+
+        if (checkCount >= maxChecks) {{
+            clearInterval(interval);
+            setStatus('未检测到API，直接尝试关闭');
+            tryClose(true);
+        }}
+    }}, 100);
+
+    setTimeout(function() {{
+        showBtn();
+    }}, 3000);
+}})();
+</script>
+</body>
+</html>"""
+
+# 保存渲染后的 HTML
+with open('/tmp/test_scan.html', 'w', encoding='utf-8') as f:
+    f.write(html)
+
+print(f"HTML rendered: {len(html)} chars")
+print("Saved to /tmp/test_scan.html")
+
+# 检查 script 部分
+import re
+script_match = re.search(r'<script>(.+?)</script>', html, re.DOTALL)
+if script_match:
+    js = script_match.group(1)
+    print(f"\nJS section: {len(js)} chars")
+    # 检查是否有 {{ 残留（f-string 未正确渲染）
+    if '{{' in js:
+        print("ERROR: Found unrendered {{ in JS!")
+        for i, line in enumerate(js.split('\n')):
+            if '{{' in line:
+                print(f"  Line {i+1}: {line.strip()[:80]}")
+    else:
+        print("OK: No unrendered braces in JS")
+    
+    # 打印前 20 行 JS
+    print("\nFirst 20 lines of rendered JS:")
+    for i, line in enumerate(js.split('\n')[:20]):
+        print(f"  {i+1}: {line}")