diff --git a/README.md b/README.md
new file mode 100644
index 0000000..95c14f4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,319 @@
+# Campux‑idoknow 校园墙系统完整部署文档
+> 基于本次成功部署流程编写，零基础可按照步骤复刻，包含全部BUG修复、宝塔操作细节、踩坑记录。
+
+## 目录
+1. 前置服务器环境要求
+2. 安装宝塔面板
+3. 宝塔内安装Docker及Docker‑Compose
+4. 域名解析配置
+5. 拉取项目源码
+6. 修改环境配置文件.env（修复第一个致命BUG）
+7. 修复开通向导机器人Platform校验BUG（前端代码修改）
+8. Docker‑Compose编译构建项目（宝塔重建按钮坑点说明）
+9. 查看容器日志，校验项目启动状态
+10. 宝塔网站配置Nginx反向代理 + 申请SSL证书
+11. 微信浏览器缓存问题解决方案
+12. NapCat‑QQ机器人对接流程
+13. 日常运维命令清单
+14. 全部踩坑问题汇总
+
+## 1. 前置服务器环境要求
+### 硬件最低配置
+- CPU：2核
+- 内存：**4G及以上（低于4G编译前端会直接卡死，构建失败）**
+- 硬盘：20GB+
+
+### 系统
+CentOS 7（优先，宝塔兼容性最佳），Ubuntu 22.04同样兼容。
+
+### 网络放行端口
+1. 服务器安全组放行：22(SSH)、80、443；
+2. 数据库、MinIO图片存储仅容器内部通信，无需对外开放端口。
+
+### 域名
+准备已备案域名，示例：`qq.yunsya.cn`，A记录解析至服务器公网IP。
+
+## 2. 安装宝塔面板
+1. 使用Xshell/FinalShell/宝塔网页终端登录服务器；
+2. CentOS7一键安装命令：
+```bash
+yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec
+ 
+ 
+3. 安装完成后，记录面板地址、账号、密码；
+4. 浏览器访问宝塔面板，阿里云/腾讯云服务器需额外在安全组放行宝塔8888端口。
+ 
+3. 宝塔安装Docker、Docker‑Compose
+ 
+1. 左侧菜单打开【软件商店】；
+2. 搜索 Docker ，点击一键安装；
+3. Docker安装完毕会自动附带Docker‑Compose；
+4. 安装完成后左侧出现【Docker】菜单。
+ 
+4. 域名解析配置
+ 
+1. 进入域名服务商后台；
+2. 添加A记录：主机记录 @ ，记录值填写服务器公网IP；
+3. 等待5‑30分钟解析生效，可通过站长工具检测。
+ 
+5. 拉取项目源码
+ 
+1. 打开宝塔【终端】，逐条执行命令：
+ 
+bash
+  
+# 进入网站根目录
+cd /www/wwwroot
+# 拉取idoknow版Campux源码，文件夹固定为campux‑source
+git clone https://github.com/idoknow/Campux.git campux-source
+# 进入项目目录
+cd campux-source
+ 
+ 
+2. 在宝塔文件管理器  /www/wwwroot  内可看到项目文件夹。
+ 
+6. 修改环境配置文件 .env
+ 
+BUG说明：原版 CAMPUX_TENANT_DOMAIN_TTL=-1 ，Zod校验不允许负数，会导致容器反复崩溃，必须修改。
+ 
+1. 宝塔文件管理器打开路径：
+ /www/wwwroot/campux-source/.env 
+2. 编辑文件，替换内容，按需修改域名与密钥：
+ 
+env
+  
+# 网站访问域名，修改为自己的HTTPS域名
+CAMPUX_WEB_ORIGIN=https://qq.yunsya.cn
+# 会话加密密钥，自行生成一串随机字母数字
+CAMPUX_BOT_SESSION_SECRET=Kd2c58e9337f54144e0d8f61d500b41f51500b41
+# 图片资源访问地址
+S3_PUBLIC_BASE_URL=https://qq.yunsya.cn/s3
+# 租户域名后缀，留空
+CAMPUX_TENANT_DOMAIN_SUFFIX=""
+# 修复BUG，由‑1改为86400秒(1天)
+CAMPUX_TENANT_DOMAIN_TTL=86400
+# 关闭遥测数据收集
+CAMPUX_TELEMETRY_DISABLED=true
+ 
+ 
+3. 保存 .env 文件。
+ 
+必改项清单
+ 
+1.  CAMPUX_WEB_ORIGIN  替换为个人域名；
+2.  CAMPUX_BOT_SESSION_SECRET  自定义随机字符串；
+3.  S3_PUBLIC_BASE_URL  替换为个人域名；
+4.  CAMPUX_TENANT_DOMAIN_TTL  修改为 86400 。
+ 
+7. 修复开通向导Platform校验BUG
+ 
+问题描述
+ 
+开通校园墙第二步「接入墙号机器人」，点击创建墙号报错：
+ invalid_union_discriminator Expected "onebot" | "official_qq" 
+原因：前端请求缺少 platform:"onebot" 字段。
+ 
+1. 打开文件路径：
+ /www/wwwroot/campux-source/apps/web/src/features/onboarding/OnboardingWizard.tsx 
+2. 找到 createBot 函数内的请求代码：
+ 
+ts
+  
+await api("/api/admin/bots", {
+  method: "POST",
+  body: JSON.stringify({
+    qqUin: botQq.trim(),
+    displayName: botName.trim() || `${tenant.name} 墙号`,
+    reviewGroupId: reviewGroup.trim() || undefined,
+    reviewNotificationEnabled: true,
+    createPublishTarget: true,
+  }),
+});
+ 
+ 
+3. 添加一行 platform: "onebot", ，修改后代码：
+ 
+ts
+  
+await api("/api/admin/bots", {
+  method: "POST",
+  body: JSON.stringify({
+    qqUin: botQq.trim(),
+    displayName: botName.trim() || `${tenant.name} 墙号`,
+    reviewGroupId: reviewGroup.trim() || undefined,
+    reviewNotificationEnabled: true,
+    createPublishTarget: true,
+    platform: "onebot",
+  }),
+});
+ 
+ 
+4. 保存文件。
+ 
+免修改备选方案
+开通向导页面返回上一页，跳过机器人绑定；校园墙创建完成后，在后台【机器人管理】页面添加QQ机器人，后台页面无此BUG。
+ 
+8. Docker‑Compose编译构建项目
+ 
+重要坑点
+ 
+宝塔移动端Docker编排里的【重建】按钮仅能重启容器，不会编译新代码，修改的TSX文件无法打包进镜像，修改不生效。必须通过终端命令构建。
+ 
+1. 打开宝塔终端，执行：
+ 
+bash
+  
+cd /www/wwwroot/campux-source
+docker compose up -d --build
+ 
+ 
+2. 构建时长4‑8分钟，全程不可关闭终端、锁屏，断开连接会终止构建。
+3. 出现如下输出，代表构建完成：
+ 
+plaintext
+  
+✔ Image campux-source-campux Built
+✔ Container campux-minio     Running
+✔ Container campux-postgres  Healthy
+✔ Container campux           Started
+ 
+ 
+自动启动3个容器：
+ 
+- campux：主程序服务
+- campux‑postgres：PostgreSQL数据库
+- campux‑minio：图片存储服务
+ 
+校验服务是否正常启动
+ 
+bash
+  
+docker logs -f campux
+ 
+ 
+出现下面两行文字即代表运行正常：
+ 
+plaintext
+  
+database migrations completed
+Server listening at http://172.18.0.4:8989
+ 
+ 
+按下 Ctrl + C 退出日志查看。
+ 
+9. 宝塔网站配置Nginx反向代理 & 申请SSL证书
+ 
+9‑1 添加站点
+ 
+1. 【网站】→【添加站点】；
+2. 域名填写： qq.yunsya.cn ；
+3. 网站目录随意填写（示例： /www/wwwroot/qq.yunsya.cn ，程序不使用该目录）；
+4. 数据库：不创建数据库；
+5. PHP版本：纯静态；
+6. 点击提交。
+ 
+9‑2 修改Nginx配置
+ 
+1. 网站列表点击【设置】‑【配置文件】；
+2. 删除全部原有代码，粘贴下方配置：
+ 
+nginx
+  
+server
+{
+    listen 80;
+    server_name qq.yunsya.cn;
+    return 301 https://$host$request_uri;
+}
+
+server
+{
+    listen 443 ssl;
+    server_name qq.yunsya.cn;
+    ssl_certificate /www/server/panel/vhost/cert/qq.yunsya.cn/fullchain.pem;
+    ssl_certificate_key /www/server/panel/vhost/cert/qq.yunsya.cn/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8989;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+
+    location /s3/ {
+        proxy_pass http://127.0.0.1:9000/campux-next/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+ 
+ 
+9‑3 申请HTTPS证书
+ 
+1. 切换到【SSL】选项卡；
+2. 选择Let‑Encrypt免费证书，勾选域名进行申请；
+3. 申请成功后开启【强制HTTPS】；
+4. 保存Nginx配置。
+ 
+保存Nginx报错提示证书不存在，代表证书未申请完成，需先完成证书申请。
+ 
+10. 微信浏览器缓存问题（必踩坑）
+ 
+Docker已经构建最新代码，但微信浏览器缓存了旧JS，表单依旧提交旧数据，依旧会报错。
+ 
+1. 手机后台彻底上滑关闭微信进程；
+2. 重新打开微信，访问域名；
+3. 再次进入开通向导，BUG修复完成。
+ 
+电脑端浏览器按 Ctrl+F5 强制刷新清除缓存。
+ 
+11. NapCat‑QQ机器人对接
+ 
+1. 校园墙开通后，复制页面内反向WebSocket地址；
+2. 打开NapCat后台，新增反向WebSocket客户端；
+3. 粘贴地址并启用；
+4. 页面状态显示「已连接」，机器人接入完成。
+ 
+12. 日常运维命令
+ 
+bash
+  
+# 查看实时日志
+docker logs -f campux
+
+# 仅重启容器(不重新构建镜像，30秒内完成)
+cd /www/wwwroot/campux-source
+docker compose restart
+
+# 更新项目源码并重新部署
+cd /www/wwwroot/campux-source
+git pull
+docker compose up -d --build
+
+# 停止整套服务
+cd /www/wwwroot/campux-source
+docker compose down
+ 
+ 
+13. 踩坑问题汇总
+ 
+1. 容器反复重启： .env 文件内 CAMPUX_TENANT_DOMAIN_TTL=-1 ，修改为86400；
+2. 开通墙号报platform错误：修改 OnboardingWizard.tsx ，添加 platform:"onebot" ；
+3. 修改代码后宝塔重建不生效：宝塔重建仅重启容器，必须执行 docker compose up -d --build ；
+4. Docker构建卡死：服务器内存低于4G，升级内存；
+5. 修改代码后网页依旧报错：微信浏览器缓存问题，彻底关闭微信；
+6. Nginx配置保存失败：SSL证书未申请完成；
+7. 域名无法访问：检查域名解析、服务器安全组、宝塔防火墙80/443端口。
+ 
+plaintext
+  
+
+### 使用方法
+1. 宝塔文件管理器进入`/www/wwwroot/campux-source`；
+2. 新建文件，命名为`README.md`；
+3. 粘贴全部文本，保存即可。
+后续迁移服务器、重装系统，直接对照本文档即可一键复现部署流程。
\ No newline at end of file